build

Documentation

Overview

Package build defines types and interfaces that could potentially be compiled to various external build-tool scripts but share a general internal abstraction and rules for escaping.

Index

• func SortFilesByDir(files []string) ([]string, map[string][]string)
• type Copy
  • func (copy Copy) Compile() []string
• type CopyAs
  • func (ca CopyAs) Compile() []string
• type CopyFrom
  • func (cf CopyFrom) Compile() []string
• type EntryPoint
  • func (ep EntryPoint) Compile() []string
• type Env
  • func Home(name string) Env
  • func (env Env) Compile() []string
• type Instruction
  • func ApplyUser(uid uint, gid uint, instructions []Instruction) []Instruction
  • func SyncFiles(files []string, dest string) []Instruction
• type Label
  • func (label Label) Compile() []string
• type Phase
  • func Phases() []Phase
• type PhaseCompileable
• type Run
  • func Chown(uid uint, gid uint, path string) Run
  • func CreateDirectories(paths []string) Run
  • func CreateDirectory(path string) Run
  • func CreateUser(name string, uid uint, gid uint) []Run
  • func (run Run) Compile() []string
• type RunAll
  • func (runAll RunAll) Compile() []string
• type User
  • func (user User) Compile() []string
• type WorkingDirectory
  • func (wd WorkingDirectory) Compile() []string

Functions

func SortFilesByDir

func SortFilesByDir(files []string) ([]string, map[string][]string)

SortFilesByDir returns both the given files indexed by parent directory and a sorted slice of those parent directories. The latter is useful in ensuring deterministic iteration since the ordering of map keys is not guaranteed.

Types

type Copy

type Copy struct {
	Sources     []string // source file/directory paths
	Destination string   // destination path
}

Copy is a concrete build instruction for copying source files/directories from the build host into the image.

func (Copy) Compile

func (copy Copy) Compile() []string

Compile quotes the defined source files/directories and destination.

type CopyAs

type CopyAs struct {
	UID uint // owner UID
	GID uint // owner GID
	Instruction
}

CopyAs is a concrete build instruction for copying source files/directories and setting their ownership to the given UID/GID.

While it can technically wrap any build.Instruction, it is meant to be used with build.Copy and build.CopyFrom to enforce file/directory ownership.

func (CopyAs) Compile

func (ca CopyAs) Compile() []string

Compile returns the variant name unquoted and all quoted CopyAs instruction fields.

type CopyFrom

type CopyFrom struct {
	From string // source variant name
	Copy
}

CopyFrom is a concrete build instruction for copying source files/directories from one variant image to another.

func (CopyFrom) Compile

func (cf CopyFrom) Compile() []string

Compile returns the variant name unquoted and all quoted Copy instruction fields.

type EntryPoint

type EntryPoint struct {
	Command []string // command and arguments
}

EntryPoint is a build instruction for declaring a container's default runtime process.

func (EntryPoint) Compile

func (ep EntryPoint) Compile() []string

Compile returns the quoted entrypoint command and arguments.

type Env

type Env struct {
	Definitions map[string]string // number of key/value pairs
}

Env is a concrete build instruction for declaring a container's runtime environment variables.

func Home

func Home(name string) Env

Home returns a build.Env instruction for setting the user's home directory.

func (Env) Compile

func (env Env) Compile() []string

Compile returns the key/value pairs as a number of `key="value"` strings where the values are properly quoted and the slice is ordered by the keys.

type Instruction

type Instruction interface {
	Compile() []string
}

Instruction defines a common interface that all concrete build types must implement.

func ApplyUser

func ApplyUser(uid uint, gid uint, instructions []Instruction) []Instruction

ApplyUser wraps any build.Copy instructions as build.CopyAs using the given UID/GID.

func SyncFiles

func SyncFiles(files []string, dest string) []Instruction

SyncFiles returns build instructions to copy over the given files after creating their parent directories. Parent directories are created in a sorted order.

type Label

type Label struct {
	Definitions map[string]string // number of meta-data key/value pairs
}

Label is a concrete build instruction for declaring a number of meta-data key/value pairs to be included in the image.

func (Label) Compile

func (label Label) Compile() []string

Compile returns the key/value pairs as a number of `key="value"` strings where the values are properly quoted and the slice is ordered by the keys.

type Phase

type Phase int

Phase enum type

const (
	PhasePrivileged       Phase = iota // first, copies/execution done as root
	PhasePrivilegeDropped              // second, copies/execution done as unprivileged user from here on
	PhasePreInstall                    // third, before application files and artifacts are copied
	PhaseInstall                       // fourth, application files and artifacts are copied
	PhasePostInstall                   // fifth, after application files and artifacts are copied
)

Distinct build phases that each compiler implementation should pass to PhaseCompileable configuration (in the order they are defined here) to allow for dependency injection during compilation.

func Phases

func Phases() []Phase

Phases returns all build phases in the order to be compiled.

type PhaseCompileable

type PhaseCompileable interface {
	InstructionsForPhase(phase Phase) []Instruction
}

PhaseCompileable defines and interface that all configuration types should implement if they want to inject build instructions into any of the defined build phases.

type Run

type Run struct {
	Command   string   // command string (e.g. "useradd -d %s -u %s")
	Arguments []string // command arguments both inner and final (e.g. ["/home/user", "123", "user"])
}

Run is a concrete build instruction for passing any number of arguments to a shell command.

The command string may contain inner argument placeholders using the "%s" format verb and will be appended with the quoted values of any arguments that remain after interpolation of the command string.

func Chown

func Chown(uid uint, gid uint, path string) Run

Chown returns a build.Run instruction for setting ownership on the given path.

func CreateDirectories

func CreateDirectories(paths []string) Run

CreateDirectories returns a build.Run instruction for creating all the given directories.

func CreateDirectory

func CreateDirectory(path string) Run

CreateDirectory returns a build.Run instruction for creating the given directory.

func CreateUser

func CreateUser(name string, uid uint, gid uint) []Run

CreateUser returns build.Run instructions for creating the given user account and group.

func (Run) Compile

func (run Run) Compile() []string

Compile quotes all arguments, interpolates the command string with inner arguments, and appends the final arguments.

type RunAll

type RunAll struct {
	Runs []Run // multiple Run instructions to be executed together
}

RunAll is a concrete build instruction for declaring multiple Run instructions that will be executed together in a `cmd1 && cmd2` chain.

func (RunAll) Compile

func (runAll RunAll) Compile() []string

Compile concatenates all individually compiled Run instructions into a single command.

type User

type User struct {
	Name string // user name
}

User is a build instruction for setting which user will run future commands.

func (User) Compile

func (user User) Compile() []string

Compile returns the quoted user name.

type WorkingDirectory

type WorkingDirectory struct {
	Path string // working directory path
}

WorkingDirectory is a build instruction for defining the working directory for future command and entrypoint instructions.

func (WorkingDirectory) Compile

func (wd WorkingDirectory) Compile() []string

Compile returns the quoted working directory path.