build

README

Build Package

The build package astracts a software build process. It is intended to be pluggable, repeatable, and with enough introspection capabilities to enable querying its state at any point.

The build package implements two abstractions to work: A runner and a run.

Runner

A runner is an interface that abstracts the process of software building. It takes some inputs, performs its job during the main method (Runner.Execute) and hopefully produces some outputs.

To envision how a runner works, we can think about the first object that implements the interface: build.Make. The Make runner gets some arguments, passes them to the make command and returns the execution status. That's it.

The runner interface is designed to be easy to implement by other processes in the future: npm, docker, etc.

Run

A run is an object that calls the Execute() method of a runner. Its job is to be keep track of the execution, make the run details available to query and transform the state and metadata into other formats.

Example Usage

// Create a build with a make runner. This is equivalent
// to running `make my-x86-target` in the current directory:
b := build.New(runners.NewMake("test-target"))

// You can set the working directory
b.Options().Workdir = "tmp/make"

// Generate a run and execute it:
b.Run().Execute()

// Launch a new Run of our build 
run := build.Run()

// We can query the run to see if it was successful:
if run.Successful() {
    fmt.Println("Run %d finished without errors", run.ID)
}

// we can print the output:
fmt.Println(run.Output())

// If we launch another run. We run the exact command again
run := build.Run()

// In an ideal world, we should get the same output. We should
// thrive to get reproducible builds.

// We can query the build to get historical data of the builds:
for i := range build.Runs {
    fmt.Println("Build #%d finished at %s", build.Runs[i].ID, build.Runs[i].EndTime.String())
}

Documentation

Index

• Constants
• Variables
• type ArtifactsConfig
• type Build
  • func New(runner runners.Runner) *Build
  • func NewFromAttestation(provenancePath string, extraOpts *Options) (*Build, error)
  • func NewFromConfigFile(configPath string) (*Build, error)
  • func NewWithOptions(runner runners.Runner, opts *Options) *Build
  • func (b *Build) Load(path string) error
  • func (b *Build) Options() *Options
  • func (b *Build) Run() *Run
  • func (b *Build) RunAttestation(path string) error
  • func (b *Build) RunWithOptions(opts *RunOptions) *Run
• type Config
  • func LoadConfig(path string) (*Config, error)
  • func (conf *Config) Validate() error
• type EnvConfig
• type MaterialsConfig
• type Options
• type ReplacementConfig
• type Run
  • func NewRun(runner runners.Runner) *Run
  • func (r *Run) Execute() error
  • func (r *Run) ID() string
  • func (r *Run) Provenance() (*intoto.ProvenanceStatement, error)
• type RunOptions
• type RunnerConfig
• type SecretConfig
• type TransferConfig

Constants

const (
	BuilderID      = "MatterBuild/v0.1"
	ConfigFileName = "matterbuild.yaml"
)

const (
	ProvenanceFilename = "provenance.json"
	DotEnvFilename     = "build.env"
	SBOMFileName       = "sbom.spdx"
)

Variables

var (
	RUNSUCCESS = true
	RUNFAIL    = false
)

var DefaultOptions = &Options{
	Workdir: ".",
	Artifacts: ArtifactsConfig{
		Files:  []string{},
		Images: []string{},
	},
	EnvVars: map[string]string{},
}

var DefaultRunOptions = &RunOptions{}

Types

type ArtifactsConfig

type ArtifactsConfig struct {
	Destination string   `yaml:"destination"` // URL to store all artifacts from the build
	Files       []string `yaml:"files"`       // List of files expected from the build
	Images      []string `yaml:"images"`      // List of container image references to be produced from this build
}

type Build

type Build struct {
	Runs         []*Run
	Replacements []replacement.Replacement
	// contains filtered or unexported fields
}

func New

func New(runner runners.Runner) *Build

New returns a new build with the default options

func NewFromAttestation

func NewFromAttestation(provenancePath string, extraOpts *Options) (*Build, error)

NewFromAttestation returns a build from the provenance attestation

func NewFromConfigFile

func NewFromConfigFile(configPath string) (*Build, error)

func NewWithOptions

func NewWithOptions(runner runners.Runner, opts *Options) *Build

func (*Build) Load

func (b *Build) Load(path string) error

LoadConfig loads the build configuration from a file

func (*Build) Options

func (b *Build) Options() *Options

Options returns the build's option set

func (*Build) Run

func (b *Build) Run() *Run

Run creates a new run

func (*Build) RunAttestation

func (b *Build) RunAttestation(path string) error

func (*Build) RunWithOptions

func (b *Build) RunWithOptions(opts *RunOptions) *Run

type Config

type Config struct {
	SBOM          bool                `yaml:"sbom"`         // When true, write an SBOM in the working dir
	ProvenanceDir string              `yaml:"provenance"`   // Directory to write provenance data
	Runner        RunnerConfig        `yaml:"runner"`       // Tag determining the runner to use
	Artifacts     ArtifactsConfig     `yaml:"artifacts"`    // Data about artifacts expected to be built
	Materials     MaterialsConfig     `yaml:"materials"`    // List of materials defined
	Secrets       []SecretConfig      `yaml:"secrets"`      // Secrets required by the build
	Env           []EnvConfig         `yaml:"env"`          // Environment vars to require/set
	Replacements  []ReplacementConfig `yaml:"replacements"` // Replacements to perform before the run
	Transfers     []TransferConfig    `yaml:"transfers"`    // List of artifacts to be transferred out after the build is done
}

func LoadConfig

func LoadConfig(path string) (*Config, error)

Load reads a config file and return a config object

func (*Config) Validate

func (conf *Config) Validate() error

Validate checks the configuration values to make sure they are complete

type EnvConfig

type EnvConfig struct {
	Var   string `yaml:"var"`   // Env var name. Will be required
	Value string `yaml:"value"` // Value. If set, the build system will set it before starting

}

type MaterialsConfig

type MaterialsConfig []struct {
	URI    string            `yaml:"uri"`    // URI to locate the source material
	Digest map[string]string `yaml:"digest"` // String to validate the material
}

type Options

type Options struct {
	ForceBuild    bool              // Execut the builder even if the expected artifacts are found
	SBOM          bool              // If true, write an SPDX sbom describing the expected artifacts
	Workdir       string            // Working directory. Usually the clone of the repo
	Source        string            // Source is the URL for the code repository
	EnvVars       map[string]string // Variables to set when running
	ProvenanceDir string            // FIrectory to save the provenance attestations
	ConfigFile    string            // If the build was bootstarpped from a build, this is it
	ConfigPoint   string            // git ref of the config file
	Transfers     []TransferConfig  // List of artifacts to transfer
	Artifacts     ArtifactsConfig   // A list of expected artifacts to be produced by the build
	Materials     MaterialsConfig   // List of materials to use for the build
}

type ReplacementConfig

type ReplacementConfig struct {
	Required      bool     `yaml:"required"`
	RequiredPaths bool     `yaml:"requiredPaths"`
	Tag           string   `yaml:"tag"`
	Value         string   `yaml:"value"`
	Paths         []string `yaml:"paths"`
	ValueFrom     struct {
		Secret string `yaml:"secret"`
		Env    string `yaml:"env"`
	} `yaml:"valueFrom"`
}

type Run

type Run struct {
	Created   time.Time
	StartTime time.Time
	EndTime   time.Time

	ProvenancePath string
	// contains filtered or unexported fields
}

Run asbtracts a build run

func NewRun

func NewRun(runner runners.Runner) *Run

NewRun creates a new running specified an options set

func (*Run) Execute

func (r *Run) Execute() error

Execute executes the run

func (*Run) ID

func (r *Run) ID() string

func (*Run) Provenance

func (r *Run) Provenance() (*intoto.ProvenanceStatement, error)

type RunOptions

type RunOptions struct {
	ForceBuild   bool             // When true, build will run even if artifacts exist already
	SBOM         bool             // Write an SBOM for the run when true
	BuildPoint   string           // git build point where the build will run
	MaterialsDir string           // Directory to store materials
	Materials    MaterialsConfig  // List of materials for the build
	Artifacts    ArtifactsConfig  // Artifacts configuration
	Transfers    []TransferConfig // Artifacts to transfer out
}

RunOptions control specific bits of a build run

type RunnerConfig

type RunnerConfig struct {
	ID         string   `yaml:"id"`
	Parameters []string `yaml:"params"`
}

type SecretConfig

type SecretConfig struct {
	Name string `yaml:"name"` // Name of the secret
}

type TransferConfig

type TransferConfig struct {
	Source      []string `yaml:"source"`      // List if files to transfer out
	Destination string   `yaml:"destination"` // An object URL where files will be copied to
}