builder

Documentation

Overview

builder is the evaluation step in the Dockerfile parse/evaluate pipeline.

It incorporates a dispatch table based on the parser.Node values (see the parser package for more information) that are yielded from the parser itself. Calling NewBuilder with the BuildOpts struct can be used to customize the experience for execution purposes only. Parsing is controlled in the parser package, and this division of resposibility should be respected.

Please see the jump table targets for the actual invocations, most of which will call out to the functions in internals.go to deal with their tasks.

ONBUILD is a special case, which is covered in the onbuild() func in dispatchers.go.

The evaluator uses the concept of "steps", which are usually each processable line in the Dockerfile. Each step is numbered and certain actions are taken before and after each step, such as creating an image ID and removing temporary containers and images. Note that ONBUILD creates a kinda-sorta "sub run" which includes its own set of steps (usually only one of them).

Index

• Variables
• type Builder
  • func (b *Builder) Run(context io.Reader) (string, error)
• type BuilderJob
  • func (b *BuilderJob) CmdBuild(job *engine.Job) engine.Status
  • func (b *BuilderJob) Install()

Variables

var (
	ErrDockerfileEmpty = errors.New("Dockerfile cannot be empty")
)

var (
	TOKEN_ENV_INTERPOLATION = regexp.MustCompile(`(\\\\+|[^\\]|\b|\A)\$({?)([[:alnum:]_]+)(}?)`)
)

Types

type Builder

type Builder struct {
	Daemon *daemon.Daemon
	Engine *engine.Engine

	// effectively stdio for the run. Because it is not stdio, I said
	// "Effectively". Do not use stdio anywhere in this package for any reason.
	OutStream io.Writer
	ErrStream io.Writer

	Verbose      bool
	UtilizeCache bool

	// controls how images and containers are handled between steps.
	Remove      bool
	ForceRemove bool

	AuthConfig     *registry.AuthConfig
	AuthConfigFile *registry.ConfigFile

	// Deprecated, original writer used for ImagePull. To be removed.
	OutOld          io.Writer
	StreamFormatter *utils.StreamFormatter

	Config *runconfig.Config // runconfig for cmd, run, entrypoint etc.

	// both of these are controlled by the Remove and ForceRemove options in BuildOpts
	TmpContainers map[string]struct{} // a map of containers used for removes
	// contains filtered or unexported fields
}

internal struct, used to maintain configuration of the Dockerfile's processing as it evaluates the parsing result.

func (*Builder) Run

func (b *Builder) Run(context io.Reader) (string, error)

Run the builder with the context. This is the lynchpin of this package. This will (barring errors):

• call readContext() which will set up the temporary directory and unpack the context into it.
• read the dockerfile
• parse the dockerfile
• walk the parse tree and execute it by dispatching to handlers. If Remove or ForceRemove is set, additional cleanup around containers happens after processing.
• Print a happy message and return the image ID.

type BuilderJob

type BuilderJob struct {
	Engine *engine.Engine
	Daemon *daemon.Daemon
}

func (*BuilderJob) CmdBuild

func (b *BuilderJob) CmdBuild(job *engine.Job) engine.Status

func (*BuilderJob) Install

func (b *BuilderJob) Install()