build

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2025 License: Apache-2.0 Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Base added in v0.12.1 

type Base struct {
	Image string // image identifier
	Stage string // optional internal name used for multi-stage builds
}

Base is a concrete build instruction for declaring the base container image to start with.

func (Base) Compile added in v0.12.1 

func (base Base) Compile(target *Target) error

Compile to the given Target

type ContextResolver added in v0.24.0 

type ContextResolver func(context.Context) (*llb.State, error)

ContextResolver returns an initialzed llb.State for a build context.

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(target *Target) error

Compile to the given Target

type CopyAs added in v0.3.0 

type CopyAs struct {
	UID string // owner UID
	GID string // 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 added in v0.3.0 

func (ca CopyAs) Compile(target *Target) error

Compile to the given Target

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(target *Target) error

Compile to the given Target

type EntryPoint added in v0.3.0 

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

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

func (EntryPoint) Compile added in v0.3.0 

func (ep EntryPoint) Compile(target *Target) error

Compile to the given Target

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 added in v0.3.0 

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(target *Target) error

Compile to the given Target

type Instruction 

type Instruction interface {
	Compile(*Target) error
}

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

func ApplyUser added in v0.3.0 

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

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

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(target *Target) error

Compile to the given Target

type Options added in v0.24.0 

type Options struct {
	// Function that returns the initial llb.State for the main build context.
	BuildContext ContextResolver

	// The target variant
	Variant string

	// Resolver used to fetch images
	MetaResolver llb.ImageMetaResolver

	// Build-time arguments
	BuildArgs map[string]string

	// Extra labels to add to the result
	Labels map[string]string

	// Build platform
	BuildPlatform oci.Platform

	// Target platforms
	TargetPlatforms []oci.Platform
}

Options stores options to configure the build process.

func NewOptions added in v0.24.0 

func NewOptions() *Options

NewOptions creates a new Options with default values assigned

func (*Options) MultiPlatform added in v0.24.0 

func (opts *Options) MultiPlatform() bool

MultiPlatform returns whether the build options contain multiple target platforms.

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 added in v0.3.0 

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 added in v0.3.0 

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

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

func CreateDirectories added in v0.5.0 

func CreateDirectories(paths []string) Run

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

func CreateDirectory added in v0.3.0 

func CreateDirectory(path string) Run

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

func CreateUser added in v0.3.0 

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

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

func (Run) Compile 

func (run Run) Compile(target *Target) error

Compile to the given Target

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 (ra RunAll) Compile(target *Target) error

Compile to the given Target

type Scanner added in v1.0.0 

type Scanner func(core llb.State, dependencies map[string]llb.State) (result.Attestation[*llb.State], error)

Scanner is a function for producing an attestion results from the internal core llb.State and dependency llb.State of a build.Target.

type ScratchBase added in v0.12.1 

type ScratchBase struct {
	Stage string // optional internal name used for multi-stage builds
}

ScratchBase is a concrete build instruction for declaring no base image.

func (ScratchBase) Compile added in v0.12.1 

func (sb ScratchBase) Compile(target *Target) error

Compile to the given Target

type StringArg added in v0.12.1 

type StringArg struct {
	Name    string // argument name
	Default string // argument default value
}

StringArg is a build instruction defining a build-time replaceable argument with a string value.

func NewStringArg added in v0.12.1 

func NewStringArg(varname string, value string) StringArg

NewStringArg creates an ARG instruction with a string default value.

func (StringArg) Compile added in v0.12.1 

func (arg StringArg) Compile(target *Target) error

Compile to the given Target

type Target added in v0.24.0 

type Target struct {
	Name    string
	Base    string
	Image   *TargetImage
	Options *Options
	// contains filtered or unexported fields
}

Target is used during compilation to keep track of build arguments, the compiled LLB state, image configuration, and dependent targets.

func NewTarget added in v0.24.0 

func NewTarget(name string, base string, platform *oci.Platform, options *Options) *Target

NewTarget constructs a Target using the given arguments and defaults

func (*Target) AddEnv added in v0.24.0 

func (target *Target) AddEnv(definitions map[string]string) error

AddEnv adds environment variables to the target build state.

Note these variables will only be defined for build time processes. To add environment variables to the resulting image config (for runtime processes when a container is later run), use [Image.AddEnv].

func (*Target) BuildContext added in v0.24.0 

func (target *Target) BuildContext() (*llb.State, error)

BuildContext returns the llb.State for the main build context

func (*Target) BuildEnv added in v0.24.0 

func (target *Target) BuildEnv() map[string]string

BuildEnv returns a full set of environment variables that should be added to build-time container processes.

func (*Target) BuildPlatform added in v0.24.0 

func (target *Target) BuildPlatform() oci.Platform

BuildPlatform returns the build platform.

func (*Target) CopyFrom added in v0.24.0 

func (target *Target) CopyFrom(from string, sources []string, destination string, options ...llb.CopyOption) error

CopyFrom copies one or more sources from the given dependency to the given destination on the target filesystem

func (*Target) CopyFromBuildContext added in v0.24.0 

func (target *Target) CopyFromBuildContext(sources []string, destination string, options ...llb.CopyOption) error

CopyFromBuildContext copies one or more sources from the main build context filesystem to the given destination on the target filesystem

func (*Target) Describef added in v0.24.0 

func (target *Target) Describef(msg string, v ...interface{}) llb.ConstraintsOpt

Describef returns an llb.ConstraintsOpt that describes a compile operation to the end user

func (*Target) ExpandEnv added in v0.24.0 

func (target *Target) ExpandEnv(subject string) string

ExpandEnv substitutes environment variable references in the given string for the current values taken from the current target state

func (*Target) ExposeBuildArg added in v0.24.0 

func (target *Target) ExposeBuildArg(name string, defaultValue string) error

ExposeBuildArg looks for a build argument and adds an environment variable for it to the target build state. If a build argument is not found, the given default value is used.

func (*Target) Initialize added in v0.24.0 

func (target *Target) Initialize(ctx context.Context) error

Initialize performs preprocessing steps, resolving the base image config, adding build-time environment variables, etc.

func (*Target) Logf added in v0.24.0 

func (target *Target) Logf(msg string, values ...interface{}) string

Logf formats logging messages for this target

func (*Target) Marshal added in v0.24.0 

func (target *Target) Marshal(ctx context.Context) (*llb.Definition, *oci.Image, error)

Marshal returns a solveable LLB definition and OCI image for this target.

func (*Target) NameLength added in v0.24.0 

func (target *Target) NameLength() int

NameLength returns the number of printable runes in the target name.

func (*Target) Platform added in v0.24.0 

func (target *Target) Platform() oci.Platform

Platform returns either the target platform given explicitly at construction or the first target platform in the options.

func (*Target) Run added in v0.24.0 

func (target *Target) Run(command string, args ...string) error

Run executes the given command and arguments using the default shell

func (*Target) RunAll added in v0.24.0 

func (target *Target) RunAll(runs ...[]string) error

RunAll executes the given set of commands and arguments as shell commands with logical &&'s (e.g. "/bin/sh -c 'cmd1 arg && cmd2 arg'")

All arguments will be quoted. The command string may contain % formatting "verbs" (a la fmt.Sprintf) for which substitutions will be made using the corresponding leading arguments. The remaining arguments will be appended.

## Example 

target.RunAll(
		string{"chown -R %s:%s", "123", "321", "/dir"},
		[]string{"chmod", "0755", "/dir"},
)

Would append a single run operation that executes: 

/bin/sh -c 'chown -R "123":"321" "/dir" && chmod "0755" "/dir"'

func (*Target) RunEntrypoint added in v0.24.0 

func (target *Target) RunEntrypoint(args []string, env map[string]string) error

RunEntrypoint runs the target's entrypoint

Note that caching is always disabled for this operation.

func (*Target) RunShell added in v0.24.0 

func (target *Target) RunShell(command string) error

RunShell runs the given command using /bin/sh

func (*Target) Scan added in v1.0.0 

func (target *Target) Scan(scanner Scanner) (result.Attestation[*llb.State], error)

Scan passes the given Scanner the llb.State for this target and all of its dependencies.

func (*Target) String added in v0.24.0 

func (target *Target) String() string

String returns the string representation of the target suitable for the user

func (*Target) User added in v0.24.0 

func (target *Target) User(user string) error

User sets the effective build time user for the target state.

Note the given user will only affect build time processes. To configure the user of the resulting image config (for runtime processes when a container is run), use [Image.User].

func (*Target) WorkingDirectory added in v0.24.0 

func (target *Target) WorkingDirectory(dir string) error

WorkingDirectory sets the build time working directory of the target state.

Note this will only affect build time processes. To configure the working directory of the resulting image config (for runtime processes when a container is run), use [Image.WorkingDirectory].

func (*Target) WriteTo added in v0.24.0 

func (target *Target) WriteTo(ctx context.Context, writer io.Writer) error

WriteTo marshals the target state to protobuf and writes it to the given io.Writer.

type TargetGroup added in v0.24.0 

type TargetGroup []*Target

TargetGroup provides interfaces for building multiple dependent targets.

func (*TargetGroup) Find added in v0.24.0 

func (tg *TargetGroup) Find(name string) (*Target, bool)

Find returns the target matching the given name or nil if none by that name are found.

func (*TargetGroup) InitializeAll added in v0.24.0 

func (tg *TargetGroup) InitializeAll(ctx context.Context) error

InitializeAll calls Target.Initialize on all targets in the group.

func (*TargetGroup) MaxNameLength added in v0.24.0 

func (tg *TargetGroup) MaxNameLength() int

MaxNameLength returns the length of the longest name in the target group.

func (*TargetGroup) NewTarget added in v0.24.0 

func (tg *TargetGroup) NewTarget(name string, base string, platform *oci.Platform, options *Options) *Target

NewTarget creates a new Target and sets its dependencies to this TargetGroup.

type TargetImage added in v0.24.0 

type TargetImage struct {
	// contains filtered or unexported fields
}

TargetImage wraps a Target and provides builder style methods for altering its internal image configuration.

func (*TargetImage) AddEnv added in v0.24.0 

func (img *TargetImage) AddEnv(env map[string]string) *TargetImage

AddEnv appends each of the given runtime environment variables of the image, overwriting an existing entry that has the same variable name.

func (*TargetImage) AddLabels added in v0.24.0 

func (img *TargetImage) AddLabels(labels map[string]string) *TargetImage

AddLabels appends the image configuration labels.

func (*TargetImage) Entrypoint added in v0.24.0 

func (img *TargetImage) Entrypoint(entrypoint []string) *TargetImage

Entrypoint sets the runtime entrypoint of the image.

func (*TargetImage) User added in v0.24.0 

func (img *TargetImage) User(user string) *TargetImage

User sets the runtime username or UID of the image.

func (*TargetImage) WorkingDirectory added in v0.24.0 

func (img *TargetImage) WorkingDirectory(path string) *TargetImage

WorkingDirectory sets the runtime working directory of the image.

type UintArg added in v0.12.1 

type UintArg struct {
	Name    string // argument name
	Default uint   // argument default value
}

UintArg is a build instruction defining a build-time replaceable argument with an integer value.

func NewUintArg added in v0.12.1 

func NewUintArg(varname string, value uint) UintArg

NewUintArg creates an ARG instruction with a uint default value.

func (UintArg) Compile added in v0.12.1 

func (arg UintArg) Compile(target *Target) error

Compile to the given Target

type User added in v0.3.0 

type User struct {
	UID string // user ID
}

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

func (User) Compile added in v0.3.0 

func (user User) Compile(target *Target) error

Compile to the given Target

type WorkingDirectory added in v0.3.0 

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 added in v0.3.0 

func (wd WorkingDirectory) Compile(target *Target) error

Compile to the given Target

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳