build

package
v0.1.9 Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2023 License: MPL-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var CacheKeyFunc = digest.CompoundID

CacheKeyFunc can be overridden by tests to generate stable strings.

View Source 
var ConfigIDFunc = func(c Config) string {
	return digest.ID(c)
}

ConfigIDFunc can be overridden in tests to generate stable config IDs.

View Source 
var Dirs = DirNames{"dist", "out", "meta"}
View Source 
var TempDirFunc = os.TempDir

TempDirFunc is the function used by this package to get the system temp dir. You can override this for testing purposes to get platform-independent paths.

Functions

func GetAllHashes 

func GetAllHashes(primary, verification Config) (crt.FileSetHashes, error)

Types

type Build 

type Build interface {
	Env() []string
	Config() Config
	CachedResult() (Result, bool, error)
	Steps() []Step
	ChangeRoot(string) error
	ChangeToVerificationRoot() error
	IsVerification() bool
	Dirs() TempDirs
}

Build represents the build of a single binary. It could be a primary build or a verification build, this Build doesn't need to know.

func New 

func New(name string, cfg Config, options ...Option) (Build, error)

func NewLocalVerification 

func NewLocalVerification(primaryRoot string, startAfter time.Time, cfg Config, options ...Option) (Build, error)

func NewPrimary 

func NewPrimary(cfg Config, opts ...Option) (Build, error)

func NewRemoteBuild 

func NewRemoteBuild(c Config, options ...Option) (Build, error)

type BuildPathsOpt added in v0.1.8 

type BuildPathsOpt func(s *pathsSettings)

func WithTargetDir added in v0.1.8 

func WithTargetDir(path string) BuildPathsOpt

type Config 

type Config struct {
	// Product is the logical product being built.
	Product crt.Product
	// BuildParameters are the invariant build parameters that must be used
	// in order to reproduce the build.
	Parameters Parameters
	// Paths are local to a build on a specific machine.
	Paths Paths
	// Tool is info about the tool that created this build.Config.
	Tool crt.Tool
	// Reproducible tells us whether the build is expected to be reproducible.
	// This is used by downstream processes.
	Reproducible bool
}

Config contains the complete configuration to build a single binary on a specific host.

func NewConfig 

func NewConfig(product crt.Product, params Parameters, paths Paths, creator crt.Tool, reproducible bool) (Config, error)

NewConfig expects product, params, and paths to be fully initialized.

func (Config) BuildResultCachePath 

func (c Config) BuildResultCachePath(verification bool) string

func (Config) ChangeRoot 

func (c Config) ChangeRoot(dir string) (Config, error)

ChangeRoot returns a copy of this Config with an updated build root.

func (Config) ChangeToRemotePrimaryRoot 

func (c Config) ChangeToRemotePrimaryRoot() (Config, error)

func (Config) ChangeToVerificationRoot 

func (c Config) ChangeToVerificationRoot() (Config, error)

func (Config) ID 

func (c Config) ID() string

ID is a unique sha256 hash of this Config.

func (Config) RemotePrimaryRoot 

func (c Config) RemotePrimaryRoot() string

func (Config) VerificationRoot 

func (c Config) VerificationRoot() string

type DirNames 

type DirNames struct {
	Target, Zip, Meta string
}

func (DirNames) List 

func (ds DirNames) List() []string

type EnvVar 

type EnvVar struct {
	Name, Description string
	// contains filtered or unexported fields
}

envVar represents a documented environment variable alongside a function showing how it is extracted from Config.

func BuildEnvDefinitions 

func BuildEnvDefinitions() []EnvVar

BuildEnvDefinitions returns the set of env vars guaranteed to be available to the build instructions, alongside a description of each one.

func BuildSpecificBuildEnvDefinitions 

func BuildSpecificBuildEnvDefinitions() []EnvVar

BuildSpecificBuildEnvDefinitions are environment variables that are expected to be different between different runs without affecting the built artifacts.

func InvariantBuildEnvDefinitions 

func InvariantBuildEnvDefinitions() []EnvVar

InvariantBuildEnvDefinitions are environment variables that should be set exactly the same for both primary build and all verification builds. Changes to these variables could change the artifacts produced.

type Inputs 

type Inputs struct {
	Product    crt.Product
	Parameters Parameters
}

Inputs represents the fixed inuputs to the build. These are identical for both the primary and verification build.

type LocalVerification 

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

LocalVerification is the local verification build. It is run inside a temporary copy of the primary build's root directory.

func (LocalVerification) CachedResult 

func (b LocalVerification) CachedResult() (Result, bool, error)

func (LocalVerification) ChangeRoot 

func (b LocalVerification) ChangeRoot(dir string) error

func (LocalVerification) ChangeToPrimaryRoot 

func (b LocalVerification) ChangeToPrimaryRoot() error

func (LocalVerification) ChangeToVerificationRoot 

func (b LocalVerification) ChangeToVerificationRoot() error

func (LocalVerification) Config 

func (b LocalVerification) Config() Config

func (LocalVerification) Dirs 

func (b LocalVerification) Dirs() TempDirs

func (LocalVerification) Env 

func (b LocalVerification) Env() []string

Env materialises the values for each defined env var as a slice compatible with exec.CMD.Env.

func (LocalVerification) IsVerification 

func (b LocalVerification) IsVerification() bool

func (*LocalVerification) Kind 

func (lv *LocalVerification) Kind() string

func (*LocalVerification) Steps 

func (lv *LocalVerification) Steps() []Step

func (LocalVerification) UpdateBuildRoot 

func (b LocalVerification) UpdateBuildRoot() error

UpdateBuildRoot updates the build root for this build depending whether it's a primary or verification build.

type Manager 

type Manager struct {
	Settings
	// contains filtered or unexported fields
}

Manager is responsible for orchestrating the running of builds. By default it will return cached build results rather then re-running a build that's already been done.

func NewManager 

func NewManager(r *Runner, opts ...Option) (*Manager, error)

func (*Manager) Build 

func (bm *Manager) Build() Build

func (*Manager) Result 

func (bm *Manager) Result() (Result, error)

Result returns the build result either from cache if present and not forcing a rebuild, or by running the build to generate a new result. The only errors that can be returned are from the attempt to load from cache, so to check if the build failed or not you still need to call the Result's Error method.

func (*Manager) ResultFromCache 

func (bm *Manager) ResultFromCache() (Result, bool, error)

func (*Manager) Runner 

func (bm *Manager) Runner() *Runner

type Meta 

type Meta struct {
	Start, Finish time.Time
	Duration      string
}

Meta captures after-the-fact information about the build. This will be different between primary and verification builds.

type Option 

type Option func(*Settings)

Option represents a function that configures Settings.

func AsPrimaryBuild 

func AsPrimaryBuild() Option

AsPrimaryBuild forces a build to be treated as a primary build (i.e. run in the current directory, or primary root (for remote builds).

func AsVerificationBuild 

func AsVerificationBuild() Option

AsVerificationBuild forces a build to be treated as a verification build (i.e. run in the verification root, and cached separately from primary builds).

func WithCleanOnly 

func WithCleanOnly(on bool) Option

WithCleanOnly causes the build to fail early if it's not based on a clean worktree.

func WithContext 

func WithContext(c context.Context) Option

WithContext sets the context passed when we shell out.

func WithDebugfunc 

func WithDebugfunc(f func(string, ...any)) Option

WithDebugfunc sest the debug func.

func WithForceRebuild 

func WithForceRebuild(on bool) Option

WithForceRebuild forces a build to be re-done rather than using cache.

func WithForceVerification 

func WithForceVerification(on bool) Option

WithForceVerification forces a build to be a verification build (or not depending on the boolean passed).

func WithLogPrefix 

func WithLogPrefix(p string) Option

WithLogPrefix sets the log prefix.

func WithLogfunc 

func WithLogfunc(f func(string, ...any)) Option

WithLogfunc sets the log func.

func WithLoudfunc 

func WithLoudfunc(f func(string, ...any)) Option

WithDebugfunc sest the debug func.

func WithStderr 

func WithStderr(w io.Writer) Option

WithStderr sets the stderr for when we shell out.

func WithStdout 

func WithStdout(w io.Writer) Option

WithStdout sets the stdout for when we shell out.

type Parameters 

type Parameters struct {
	// GoVersion is the version of the Go toolchain to run thid build with.
	GoVersion string `env:"GO_VERSION"`
	// Instructions are the build instructions (a bash script).
	Instructions string `env:"INSTRUCTIONS"`
	// OS is the target OS for this build.
	OS string `env:"OS"`
	// Arch is the target Architecture for this build.
	Arch string `env:"ARCH"`
	// ZipName is the name of the zip file to create.
	ZipName string `env:"ZIP_NAME"`
}

Parameters are the set of build inputs that should be enough (along with the Product) to reproduce a build. Changes to these should result in different build outputs.

func (Parameters) Init 

func (bp Parameters) Init(p crt.Product) (Parameters, error)

type Paths 

type Paths struct {
	// WorkDir is the absolute directory to run the build instructions in.
	WorkDir string
	// BinPath is the absolute path to the executable binary the instructions
	// must create.
	BinPath string
	// ZipPath is the path to the zip file that will be created.
	ZipPath string
	// MetaDir is where we write metadata about this build.
	MetaDir string
}

Paths are host-specific absolute paths to various things. We need to be aware of these paths in order to be able to do comparisons between primary and verification builds. They must not affect the bytes produced.

func NewBuildPaths 

func NewBuildPaths(root, executableName, zipName string, opts ...BuildPathsOpt) (Paths, error)

func (Paths) TargetDir 

func (bp Paths) TargetDir() string

TargetDir is the absolute path to the dir where any other files needed to be included in the zip file should be placed.

func (Paths) ZipDir 

func (bp Paths) ZipDir() string

type Primary 

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

Primary is the primary build. This is run in the current working directory, using whatever files are present.

func (Primary) CachedResult 

func (b Primary) CachedResult() (Result, bool, error)

func (Primary) ChangeRoot 

func (b Primary) ChangeRoot(dir string) error

func (Primary) ChangeToPrimaryRoot 

func (b Primary) ChangeToPrimaryRoot() error

func (Primary) ChangeToVerificationRoot 

func (b Primary) ChangeToVerificationRoot() error

func (Primary) Config 

func (b Primary) Config() Config

func (Primary) Dirs 

func (b Primary) Dirs() TempDirs

func (Primary) Env 

func (b Primary) Env() []string

Env materialises the values for each defined env var as a slice compatible with exec.CMD.Env.

func (Primary) IsVerification 

func (b Primary) IsVerification() bool

func (*Primary) Kind 

func (p *Primary) Kind() string

func (Primary) Steps 

func (b Primary) Steps() []Step

func (Primary) UpdateBuildRoot 

func (b Primary) UpdateBuildRoot() error

UpdateBuildRoot updates the build root for this build depending whether it's a primary or verification build.

type RemoteBuild 

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

RemoteBuild is a build where the source code is hosted remotely. This can be a "primary" or verification build.

func (RemoteBuild) CachedResult 

func (b RemoteBuild) CachedResult() (Result, bool, error)

func (RemoteBuild) ChangeRoot 

func (b RemoteBuild) ChangeRoot(dir string) error

func (RemoteBuild) ChangeToPrimaryRoot 

func (b RemoteBuild) ChangeToPrimaryRoot() error

func (RemoteBuild) ChangeToVerificationRoot 

func (b RemoteBuild) ChangeToVerificationRoot() error

func (RemoteBuild) Config 

func (b RemoteBuild) Config() Config

func (RemoteBuild) Dirs 

func (b RemoteBuild) Dirs() TempDirs

func (RemoteBuild) Env 

func (b RemoteBuild) Env() []string

Env materialises the values for each defined env var as a slice compatible with exec.CMD.Env.

func (RemoteBuild) IsVerification 

func (b RemoteBuild) IsVerification() bool

func (*RemoteBuild) Steps 

func (rb *RemoteBuild) Steps() []Step

func (RemoteBuild) UpdateBuildRoot 

func (b RemoteBuild) UpdateBuildRoot() error

UpdateBuildRoot updates the build root for this build depending whether it's a primary or verification build.

type Result 

type Result struct {
	Config     Config
	Env        []string
	Meta       Meta
	Zip        crt.File
	Executable crt.File

	ErrorMessage string `json:",omitempty"`
	Successful   bool
	// contains filtered or unexported fields
}

Result captures a single binary build. It's used for both primary and verification builds. Note that the Config will be different for each of them because it contains build-host-specific paths.

func (Result) Error 

func (br Result) Error() error

func (Result) IsFromCache 

func (br Result) IsFromCache() bool

func (Result) Result 

func (br Result) Result() (Result, error)

Result makes BuildResult a ResultSource which can be used by the verifier.

func (Result) Save 

func (br Result) Save(isVerification bool) (string, error)

type ResultSource 

type ResultSource interface {
	Result() (Result, error)
}

type Runner 

type Runner struct {
	Settings
	// contains filtered or unexported fields
}

Runner is responsible for executing and logging build steps and constructing the build Result.

func NewRunner 

func NewRunner(b Build, opts ...Option) (*Runner, error)

func (*Runner) Failed 

func (br *Runner) Failed() bool

func (*Runner) RecordBin 

func (br *Runner) RecordBin(path string) error

func (*Runner) RecordZip 

func (br *Runner) RecordZip(path string) error

func (*Runner) Result 

func (br *Runner) Result() Result

func (*Runner) Run 

func (br *Runner) Run() Result

type Settings 

type Settings struct {
	Log   func(string, ...any)
	Debug func(string, ...any)
	Loud  func(string, ...any)
	// contains filtered or unexported fields
}

Settings contains settings for running builds. These are not to be confused with build.Config, these settings are build-run specific and not part of the _definition_ of the build. Don't use this directly, use the With... functions to set settings when calling New.

type Step 

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

type StepFunc 

type StepFunc func() error

type TempDirs 

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

func NewPrimaryDirs 

func NewPrimaryDirs(p crt.Product, params Parameters, t crt.Tool) TempDirs

func NewTempDirs 

func NewTempDirs(kind string, p crt.Product, params Parameters, t crt.Tool) TempDirs

func NewVerificationDirs 

func NewVerificationDirs(p crt.Product, params Parameters, t crt.Tool) TempDirs

func (TempDirs) BuildResultCacheDir 

func (d TempDirs) BuildResultCacheDir(extension ...string) string

func (TempDirs) Key 

func (ck TempDirs) Key() string

func (TempDirs) RemoteBuildRoot 

func (d TempDirs) RemoteBuildRoot(extension ...string) string

func (TempDirs) SourceDownloadDir 

func (d TempDirs) SourceDownloadDir() string

func (TempDirs) VerificationResultCachePath 

func (d TempDirs) VerificationResultCachePath(configID, zipName string) string

type VerificationResult 

type VerificationResult struct {
	Primary             *Result
	Verification        *Result
	Hashes              crt.FileSetHashes
	ErrorMessage        string `json:",omitempty"`
	Dirty               bool
	ReproducedCorrectly bool
}

VerificationResult captures the result of a primary and local verification build together with easy-access hashes and an overall "reproduced correctly" boolean.

func (*VerificationResult) Error 

func (vr *VerificationResult) Error() error

func (*VerificationResult) IsFromCache 

func (vr *VerificationResult) IsFromCache() bool

type Verifier 

type Verifier struct {
	Settings
	// contains filtered or unexported fields
}

func NewVerifier 

func NewVerifier(primary, verification ResultSource, opts ...Option) (*Verifier, error)

func (*Verifier) Verify 

func (v *Verifier) Verify() (*VerificationResult, error)

Verify returns a VerificationResult which may or may not be affirmative. It returns an error when issues occur discovering that result, not when the result itself says that the reproduction didn't work. You still need to query the result to find out if it was successful.

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.