From 515d9f26eb616a9c3a0b70ba6eca88570a15b0ef Mon Sep 17 00:00:00 2001 From: Dan Duvall Date: Tue, 24 Oct 2017 18:04:47 -0700 Subject: Documented all exported types, functions, and interfaces Summary: Wrote inline documentation for all the things. Fixes T168000 Test Plan: Execute `godoc -http=:6060` and proofread all the things. Reviewers: thcipriani, hashar, #release-engineering-team, demon Reviewed By: thcipriani, #release-engineering-team, demon Tags: #release-engineering-team Maniphest Tasks: T168000 Differential Revision: https://phabricator.wikimedia.org/D841 --- build/instructions.go | 72 ++++++++++++++++++++++++++++++++++++++++++--------- build/phases.go | 19 ++++++++++---- 2 files changed, 74 insertions(+), 17 deletions(-) (limited to 'build') diff --git a/build/instructions.go b/build/instructions.go index 41c959d..3035b9f 100644 --- a/build/instructions.go +++ b/build/instructions.go @@ -1,3 +1,7 @@ +// 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. +// package build import ( @@ -7,15 +11,28 @@ import ( "strings" ) +// Instruction defines a common interface that all concrete build types must +// implement. +// type Instruction interface { Compile() []string } +// 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. +// type Run struct { - Command string - Arguments []string + 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"]) } +// Compile quotes all arguments, interpolates the command string with inner +// arguments, and appends the final arguments. +// func (run Run) Compile() []string { numInnerArgs := strings.Count(run.Command, `%`) - strings.Count(run.Command, `%%`) command := sprintf(run.Command, run.Arguments[0:numInnerArgs]) @@ -27,10 +44,16 @@ func (run Run) Compile() []string { return []string{command} } +// RunAll is a concrete build instruction for declaring multiple Run +// instructions that will be executed together in a `cmd1 && cmd2` chain. +// type RunAll struct { - Runs []Run + Runs []Run // multiple Run instructions to be executed together } +// Compile concatenates all individually compiled Run instructions into a +// single command. +// func (runAll RunAll) Compile() []string { commands := make([]string, len(runAll.Runs)) @@ -41,47 +64,72 @@ func (runAll RunAll) Compile() []string { return []string{strings.Join(commands, " && ")} } +// Copy is a concrete build instruction for copying source files/directories +// from the build host into the image. +// type Copy struct { - Sources []string - Destination string + Sources []string // source file/directory paths + Destination string // destination path } +// Compile quotes the defined source files/directories and destination. +// func (copy Copy) Compile() []string { return append(quoteAll(copy.Sources), quote(copy.Destination)) } +// CopyFrom is a concrete build instruction for copying source +// files/directories from one variant image to another. +// type CopyFrom struct { - From string + From string // source variant name Copy } +// Compile returns the variant name unquoted and all quoted Copy instruction +// fields. +// func (cf CopyFrom) Compile() []string { return append([]string{cf.From}, cf.Copy.Compile()...) } +// Env is a concrete build instruction for declaring a container's runtime +// environment variables. +// type Env struct { - Definitions map[string]string + Definitions map[string]string // number of key/value pairs } +// 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. +// func (env Env) Compile() []string { return compileSortedKeyValues(env.Definitions) } -// Label represents a 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. +// type Label struct { - Definitions map[string]string + Definitions map[string]string // number of meta-data key/value pairs } -// Compile returns the label key/value pairs as a number of `key="value"` -// strings where the values are properly quoted +// 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. +// func (label Label) Compile() []string { return compileSortedKeyValues(label.Definitions) } +// Volume is a concrete build instruction for defining a volume mount point +// within the container. +// type Volume struct { - Path string + Path string // volume/mount path } +// Compile returns the quoted volume path. +// func (vol Volume) Compile() []string { return []string{quote(vol.Path)} } diff --git a/build/phases.go b/build/phases.go index 02e84e4..3480927 100644 --- a/build/phases.go +++ b/build/phases.go @@ -1,15 +1,24 @@ package build +// Phase enum type type Phase int +// 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. +// const ( - PhasePrivileged Phase = iota - PhasePrivilegeDropped - PhasePreInstall - PhaseInstall - PhasePostInstall + 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 ) +// 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 PhaseCompileable interface { InstructionsForPhase(phase Phase) []Instruction } -- cgit v1.2.1