builder

Documentation

Overview

Package 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

• Constants
• func Build(d *daemon.Daemon, buildConfig *Config) error
• func BuildFromConfig(d *daemon.Daemon, c *runconfig.Config, changes []string) (*runconfig.Config, error)
• func Commit(d *daemon.Daemon, name string, c *daemon.ContainerCommitConfig) (string, error)
• func ContainsWildcards(name string) bool
• func ProcessWord(word string, env []string) (string, error)
• type Builder
  • func (b *Builder) Run(context io.Reader) (string, error)
• type Config
  • func NewBuildConfig() *Config
  • func (b *Config) Cancel()
  • func (b *Config) WaitCancelled() <-chan struct{}

Constants

const (
	// NoBaseImageSpecifier is the symbol used by the FROM
	// command to specify that no base image is to be used.
	NoBaseImageSpecifier string = "scratch"
)

Functions

func Build

func Build(d *daemon.Daemon, buildConfig *Config) error

func BuildFromConfig

func BuildFromConfig(d *daemon.Daemon, c *runconfig.Config, changes []string) (*runconfig.Config, error)

func Commit

func Commit(d *daemon.Daemon, name string, c *daemon.ContainerCommitConfig) (string, error)

func ContainsWildcards

func ContainsWildcards(name string) bool

func ProcessWord

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

Types

type Builder

type Builder struct {
	Daemon *daemon.Daemon

	// 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
	Pull        bool

	AuthConfig *cliconfig.AuthConfig
	ConfigFile *cliconfig.ConfigFile

	// Deprecated, original writer used for ImagePull. To be removed.
	OutOld          io.Writer
	StreamFormatter *streamformatter.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 Config

type Config struct {
	DockerfileName string
	RemoteURL      string
	RepoName       string
	SuppressOutput bool
	NoCache        bool
	Remove         bool
	ForceRemove    bool
	Pull           bool
	JSONFormat     bool
	Memory         int64
	MemorySwap     int64
	CpuShares      int64
	CpuQuota       int64
	CpuSetCpus     string
	CpuSetMems     string
	AuthConfig     *cliconfig.AuthConfig
	ConfigFile     *cliconfig.ConfigFile

	Stdout  io.Writer
	Context io.ReadCloser
	// contains filtered or unexported fields
}

func NewBuildConfig

func NewBuildConfig() *Config

func (*Config) Cancel

func (b *Config) Cancel()

When called, causes the Job.WaitCancelled channel to unblock.

func (*Config) WaitCancelled

func (b *Config) WaitCancelled() <-chan struct{}

Returns a channel which is closed ("never blocks") when the job is cancelled.