dockerfile

Documentation

Overview

Package dockerfile 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 responsibility 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
• Variables
• func BuildFromConfig(config *runconfig.Config, changes []string) (*runconfig.Config, error)
• func Commit(containerName string, d *daemon.Daemon, c *CommitConfig) (string, error)
• func ProcessWord(word string, env []string) (string, error)
• func ProcessWords(word string, env []string) ([]string, error)
• type BFlags
  • func NewBFlags() *BFlags
  • func (bf *BFlags) AddBool(name string, def bool) *Flag
  • func (bf *BFlags) AddString(name string, def string) *Flag
  • func (bf *BFlags) Parse() error
• type Builder
  • func NewBuilder(config *Config, docker builder.Docker, context builder.Context, ...) (b *Builder, err error)
  • func (b *Builder) Build() (string, error)
  • func (b *Builder) Cancel()
• type CommitConfig
• type Config
• type Flag
  • func (fl *Flag) IsTrue() bool
  • func (fl *Flag) IsUsed() bool
• type FlagType

Constants

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

Variables

var BuiltinAllowedBuildArgs = map[string]bool{
	"HTTP_PROXY":  true,
	"http_proxy":  true,
	"HTTPS_PROXY": true,
	"https_proxy": true,
	"FTP_PROXY":   true,
	"ftp_proxy":   true,
	"NO_PROXY":    true,
	"no_proxy":    true,
}

BuiltinAllowedBuildArgs is list of built-in allowed build args

Functions

func BuildFromConfig

func BuildFromConfig(config *runconfig.Config, changes []string) (*runconfig.Config, error)

BuildFromConfig will do build directly from parameter 'changes', which comes from Dockerfile entries, it will: - call parse.Parse() to get AST root from Dockerfile entries - do build by calling builder.dispatch() to call all entries' handling routines TODO: remove?

func Commit

func Commit(containerName string, d *daemon.Daemon, c *CommitConfig) (string, error)

Commit will create a new image from a container's changes TODO: remove daemon, make Commit a method on *Builder ?

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.

Types

type BFlags

type BFlags struct {
	Args []string // actual flags/args from cmd line

	Err error
	// contains filtered or unexported fields
}

BFlags contains all flags information for the builder

func NewBFlags

func NewBFlags() *BFlags

NewBFlags return the new BFlags struct

func (*BFlags) AddBool

func (bf *BFlags) AddBool(name string, def bool) *Flag

AddBool adds a bool flag to BFlags Note, any error will be generated when Parse() is called (see Parse).

func (*BFlags) AddString

func (bf *BFlags) AddString(name string, def string) *Flag

AddString adds a string flag to BFlags Note, any error will be generated when Parse() is called (see Parse).

func (*BFlags) Parse

func (bf *BFlags) Parse() error

Parse parses and checks if the BFlags is valid. Any error noticed during the AddXXX() funcs will be generated/returned here. We do this because an error during AddXXX() is more like a compile time error so it doesn't matter too much when we stop our processing as long as we do stop it, so this allows the code around AddXXX() to be just:

defFlag := AddString("description", "")

w/o needing to add an if-statement around each one.

type Builder

type Builder struct {
	*Config

	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Builder is a Dockerfile builder It implements the builder.Builder interface.

func NewBuilder

func NewBuilder(config *Config, docker builder.Docker, context builder.Context, dockerfile io.ReadCloser) (b *Builder, err error)

NewBuilder creates a new Dockerfile builder from an optional dockerfile and a Config. If dockerfile is nil, the Dockerfile specified by Config.DockerfileName, will be read from the Context passed to Build().

func (*Builder) Build

func (b *Builder) Build() (string, error)

Build runs the Dockerfile builder from a context and a docker object that allows to make calls to Docker.

This will (barring errors):

• read the dockerfile from context
• parse the dockerfile if not already parsed
• walk the AST 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.
• NOT tag the image, that is responsibility of the caller.

func (*Builder) Cancel

func (b *Builder) Cancel()

Cancel cancels an ongoing Dockerfile build.

type CommitConfig

type CommitConfig struct {
	Pause   bool
	Repo    string
	Tag     string
	Author  string
	Comment string
	Changes []string
	Config  *runconfig.Config
}

CommitConfig contains build configs for commit operation

type Config

type Config struct {
	// only used if Dockerfile has to be extracted from Context
	DockerfileName string

	Verbose     bool
	UseCache    bool
	Remove      bool
	ForceRemove bool
	Pull        bool
	BuildArgs   map[string]string // build-time args received in build context for expansion/substitution and commands in 'run'.
	Isolation   runconfig.IsolationLevel

	Memory       int64
	MemorySwap   int64
	ShmSize      *int64
	CPUShares    int64
	CPUPeriod    int64
	CPUQuota     int64
	CPUSetCpus   string
	CPUSetMems   string
	CgroupParent string
	Ulimits      []*ulimit.Ulimit
}

Config constitutes the configuration for a Dockerfile builder.

type Flag

type Flag struct {
	Value string
	// contains filtered or unexported fields
}

Flag contains all information for a flag

func (*Flag) IsTrue

func (fl *Flag) IsTrue() bool

IsTrue checks if a bool flag is true

func (*Flag) IsUsed

func (fl *Flag) IsUsed() bool

IsUsed checks if the flag is used

type FlagType

type FlagType int

FlagType is the type of the build flag