builder

Documentation

Overview

Package builder uses code from github.com/docker/docker/builder/* to implement a Docker builder that does not create individual layers, but instead creates a single layer.

TODO: full windows support

Index

• Constants
• Variables
• func ParseDockerignore(root string) ([]string, error)
• func ProcessWord(word string, env []string) (string, error)
• func ProcessWords(word string, env []string) ([]string, error)
• func SplitChildren(node *parser.Node, value string) []*parser.Node
• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) Arguments() []string
  • func (b *Builder) Config() *docker.Config
  • func (b *Builder) From(node *parser.Node) (string, error)
  • func (b *Builder) FromImage(image *docker.Image, node *parser.Node) error
  • func (b *Builder) RequiresStart(node *parser.Node) bool
  • func (b *Builder) Run(step *Step, exec Executor) error
  • func (b *Builder) Step() *Step
• type ClientExecutor
  • func NewClientExecutor(client *docker.Client) *ClientExecutor
  • func (e *ClientExecutor) Archive(src, dst string, allowDecompression, allowDownload bool) (io.Reader, io.Closer, error)
  • func (e *ClientExecutor) Build(r io.Reader, args map[string]string) error
  • func (e *ClientExecutor) Cleanup() error
  • func (e *ClientExecutor) CleanupImage(name string) error
  • func (e *ClientExecutor) Copy(copies ...Copy) error
  • func (e *ClientExecutor) CreateScratchImage() (string, error)
  • func (e *ClientExecutor) LoadImage(from string) (*docker.Image, error)
  • func (e *ClientExecutor) Run(run Run, config docker.Config) error
• type Copy
• type CopyInfo
  • func CalcCopyInfo(origPath, rootPath string, allowLocalDecompression, allowWildcards bool) ([]CopyInfo, error)
  • func DownloadURL(src, dst string) ([]CopyInfo, string, error)
• type Executor
• type Run
• type Step
  • func (b *Step) Resolve(ast *parser.Node) error
• type StepFunc

Constants

const (
	// in docker/system
	NoBaseImageSpecifier = "scratch"
)

Variables

var (
	LogExecutor  = logExecutor{}
	NoopExecutor = noopExecutor{}
)

var ErrNoFROM = fmt.Errorf("no FROM statement found")

ErrNoFROM is returned if the Dockerfile did not contain a FROM statement.

Functions

func ParseDockerignore

func ParseDockerignore(root string) ([]string, error)

ParseDockerIgnore returns a list of the excludes in the .dockerignore file. extracted from fsouza/go-dockerclient.

func ProcessWord

func ProcessWord(word string, env []string) (string, error)

ProcessWord will use the 'env' list of environment variables, and replace any env var references in 'word'.

func ProcessWords

func ProcessWords(word string, env []string) ([]string, error)

ProcessWords will use the 'env' list of environment variables, and replace any env var references in 'word' then it will also return a slice of strings which represents the 'word' split up based on spaces - taking into account quotes. Note that this splitting is done **after** the env var substitutions are done. Note, each one is trimmed to remove leading and trailing spaces (unless they are quoted", but ProcessWord retains spaces between words.

func SplitChildren

func SplitChildren(node *parser.Node, value string) []*parser.Node

SplitChildren removes any children with the provided value from node and returns them as an array. node.Children is updated.

Types

type Builder

type Builder struct {
	RunConfig docker.Config

	Env    []string
	Args   map[string]string
	CmdSet bool
	Author string

	AllowedArgs map[string]bool

	PendingRuns   []Run
	PendingCopies []Copy

	Executor Executor
}

func NewBuilder

func NewBuilder() *Builder

func (*Builder) Arguments

func (b *Builder) Arguments() []string

Arguments returns the currently active arguments.

func (*Builder) Config

func (b *Builder) Config() *docker.Config

Config returns a snapshot of the current RunConfig intended for use with a container commit.

func (*Builder) From

func (b *Builder) From(node *parser.Node) (string, error)

From returns the image this dockerfile depends on, or an error if no FROM is found or if multiple FROM are specified. If a single from is found the passed node is updated with only the remaining statements. The builder's RunConfig.Image field is set to the first From found, or left unchanged if already set.

func (*Builder) FromImage

func (b *Builder) FromImage(image *docker.Image, node *parser.Node) error

FromImage updates the builder to use the provided image (resetting RunConfig and recording the image environment), and updates the node with any ONBUILD statements extracted from the parent image.

func (*Builder) RequiresStart

func (b *Builder) RequiresStart(node *parser.Node) bool

RequiresStart returns true if a running container environment is necessary to invoke the provided commands

func (*Builder) Run

func (b *Builder) Run(step *Step, exec Executor) error

Run executes a step, transforming the current builder and invoking any Copy or Run operations.

func (*Builder) Step

func (b *Builder) Step() *Step

Step creates a new step from the current state.

type ClientExecutor

type ClientExecutor struct {
	// Client is a client to a Docker daemon.
	Client *docker.Client
	// Directory is the context directory to build from, will use
	// the current working directory if not set.
	Directory string
	// Excludes are a list of file patterns that should be excluded
	// from the context. Will be set to the contents of the
	// .dockerignore file if nil.
	Excludes []string
	// Tag is an optional value to tag the resulting built image.
	Tag string
	// AllowPull when set will pull images that are not present on
	// the daemon.
	AllowPull bool

	Out, ErrOut io.Writer

	// Container is optional and can be set to a container to use as
	// the execution environment for a build.
	Container *docker.Container
	// Command, if set, will be used as the entrypoint for the new
	// container. This is ignored if Container is set.
	Command []string
	// Image is optional and may be set to control which image is used
	// as a base for this build. Otherwise the FROM value from the
	// Dockerfile is read (will be pulled if not locally present).
	Image *docker.Image

	// AuthFn will handle authenticating any docker pulls if Image
	// is set to nil.
	AuthFn func(name string) ([]docker.AuthConfiguration, bool)
	// HostConfig is used to start the container (if necessary).
	HostConfig *docker.HostConfig
	// LogFn is an optional command to log information to the end user
	LogFn func(format string, args ...interface{})
}

ClientExecutor can run Docker builds from a Docker client.

func NewClientExecutor

func NewClientExecutor(client *docker.Client) *ClientExecutor

NewClientExecutor creates a client executor.

func (*ClientExecutor) Archive

func (e *ClientExecutor) Archive(src, dst string, allowDecompression, allowDownload bool) (io.Reader, io.Closer, error)

func (*ClientExecutor) Build

func (e *ClientExecutor) Build(r io.Reader, args map[string]string) error

Build is a helper method to perform a Docker build against the provided Docker client. It will load the image if not specified, create a container if one does not already exist, and start a container if the Dockerfile contains RUN commands. It will cleanup any containers it creates directly, and set the e.Image.ID field to the generated image.

func (*ClientExecutor) Cleanup

func (e *ClientExecutor) Cleanup() error

Cleanup will remove the container that created the build.

func (*ClientExecutor) CleanupImage

func (e *ClientExecutor) CleanupImage(name string) error

CleanupImage attempts to remove the provided image.

func (*ClientExecutor) Copy

func (e *ClientExecutor) Copy(copies ...Copy) error

func (*ClientExecutor) CreateScratchImage

func (e *ClientExecutor) CreateScratchImage() (string, error)

CreateScratchImage creates a new, zero byte layer that is identical to "scratch" except that the resulting image will have two layers.

func (*ClientExecutor) LoadImage

func (e *ClientExecutor) LoadImage(from string) (*docker.Image, error)

LoadImage checks the client for an image matching from. If not found, attempts to pull the image and then tries to inspect again.

func (*ClientExecutor) Run

func (e *ClientExecutor) Run(run Run, config docker.Config) error

Run executes a single Run command against the current container using exec(). Since exec does not allow ENV or WORKINGDIR to be set, we force the execution of the user command into a shell and perform those operations before. Since RUN requires /bin/sh, we can use both 'cd' and 'export'.

type Copy

type Copy struct {
	Src      string
	Dest     []string
	Download bool
}

Copy defines a copy operation required on the container.

type CopyInfo

type CopyInfo struct {
	os.FileInfo
	Path       string
	Decompress bool
	FromDir    bool
}

func CalcCopyInfo

func CalcCopyInfo(origPath, rootPath string, allowLocalDecompression, allowWildcards bool) ([]CopyInfo, error)

CalcCopyInfo identifies the source files selected by a Dockerfile ADD or COPY instruction.

func DownloadURL

func DownloadURL(src, dst string) ([]CopyInfo, string, error)

type Executor

type Executor interface {
	Copy(copies ...Copy) error
	Run(run Run, config docker.Config) error
}

type Run

type Run struct {
	Shell bool
	Args  []string
}

Run defines a run operation required in the container.

type Step

type Step struct {
	Env []string

	Command  string
	Args     []string
	Flags    []string
	Attrs    map[string]bool
	Message  string
	Original string
}

Step represents the input Env and the output command after all post processing of the command arguments is done.

func (*Step) Resolve

func (b *Step) Resolve(ast *parser.Node) error

Resolve transforms a parsed Dockerfile line into a command to execute, resolving any arguments.

Almost all nodes will have this structure: Child[Node, Node, Node] where Child is from parser.Node.Children and each node comes from parser.Node.Next. This forms a "line" with a statement and arguments and we process them in this normalized form by hitting evaluateTable with the leaf nodes of the command and the Builder object.

ONBUILD is a special case; in this case the parser will emit: Child[Node, Child[Node, Node...]] where the first node is the literal "onbuild" and the child entrypoint is the command of the ONBUILD statement, such as `RUN` in ONBUILD RUN foo. There is special case logic in here to deal with that, at least until it becomes more of a general concern with new features.

type StepFunc

type StepFunc func(*Builder, []string, map[string]bool, string) error

StepFunc is invoked with the result of a resolved step.