builder

Documentation

Overview

Package builder is a driver for Go builds

It does about the following

GOWORK=off
cd $(mktemp -d)
go mod init _
go get <path>@<version>
go build -o <output> <path>

Example Usage

// prepare the build environment (creates a temporary directory, go
// gets the required packages)
builder, err := New("go.schlittermann.de/heiko/hello")
if err != nil { … }

// set a global timeout for the whole build process
ctx, cancel := context.WithTimeout(context.Background(), 120 * time.Second)
defer cancel()

// get the required module
err = builder.Get(ctx)
if err != nil { … }

res, err := builder.Build(ctx, "linux", "amd64")
if err != nil { … }

log.Println("build info:", build.Result.BuildInfo)

Index

• func GetTest(yes bool) func(*bool)
• func RunTest(test string, flags ...string) buildOption
• func SkipTest(yes bool) buildOption
• func TestArgs(args ...string) buildOption
• type Build
  • func (b *Build) Wait() (*Result, error)
• type Builder
  • func New(mainPath string, options ...Option) (_ *Builder, err error)
  • func (b *Builder) Build(ctx context.Context, os, arch string, options ...buildOption) (*Result, error)
  • func (b *Builder) Cleanup()
  • func (b *Builder) Command(argv0 string, args ...string) (cmd *exec.Cmd)
  • func (b *Builder) CommandContext(ctx context.Context, argv0 string, args ...string) (cmd *exec.Cmd)
  • func (b *Builder) FindTargets(ss []string) (Targets, error)
  • func (b *Builder) Get(ctx context.Context, withTest ...func(*bool)) (err error)
  • func (b *Builder) Start(ctx context.Context, goos, goarch string, options ...buildOption) (build *Build, err error)
  • func (b *Builder) System(argv0 string, args ...string) error
• type Option
  • func WithCommit(c string) Option
  • func WithEnv(env ...string) Option
  • func WithEnvMap(env map[string]string) Option
• type Result
• type Targets
  • func (tt Targets) Match(pattern string) iter.Seq[target]

Functions

func GetTest

func GetTest(yes bool) func(*bool)

GetTest disables fetching the test dependencies

func RunTest

func RunTest(test string, flags ...string) buildOption

RunTest sets the test to be run prior build (passed to "go test -run) and options

func SkipTest

func SkipTest(yes bool) buildOption

SkipTest Build option disables running the tests during build

func TestArgs

func TestArgs(args ...string) buildOption

TestArgs set the args which can follow the "-args" option for the test command

Types

type Build

type Build struct {
	*Builder

	Target target
	// contains filtered or unexported fields
}

Build is a build, which may be started or running. Once it finishes, it returns a Result.

func (*Build) Wait

func (b *Build) Wait() (*Result, error)

Wait waits for the running build process and populates the Build.Result structure once it finished

type Builder

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

Builder represents a builder, which may have many have child builds

func New

func New(mainPath string, options ...Option) (_ *Builder, err error)

New creates a new builder. The caller must call Cleanup once they're done, to make sure that the temporary directory gets removed. It starts "go get …" in the background, the result can be fetched explicitly using Wait, or implicitly with Start.

func (*Builder) Build

func (b *Builder) Build(ctx context.Context, os, arch string, options ...buildOption) (*Result, error)

Build starts the build and waits for its completion

func (*Builder) Cleanup

func (b *Builder) Cleanup()

Cleanup purges the build environment (removes the temporary directory)

func (*Builder) Command

func (b *Builder) Command(argv0 string, args ...string) (cmd *exec.Cmd)

Command returns a exec.Cmd which will run within the tmpdir of the Builder. The output channels are connected to the respective channels of the os.

func (*Builder) CommandContext

func (b *Builder) CommandContext(ctx context.Context, argv0 string, args ...string) (cmd *exec.Cmd)

CommandContext returns a exec.Cmd with the context set. The directory of the command is set to the directory of b

func (*Builder) FindTargets

func (b *Builder) FindTargets(ss []string) (Targets, error)

FindTargets expands the list of "os/arch" to a more structured list.

func (*Builder) Get

func (b *Builder) Get(ctx context.Context, withTest ...func(*bool)) (err error)

Get downloads the required module. A specific commit can be given using the WithCommit method.

func (*Builder) Start

func (b *Builder) Start(ctx context.Context, goos, goarch string, options ...buildOption) (build *Build, err error)

Start starts a new build process for the given os and arch. The build then runs in the background and needs to be waited for.

func (*Builder) System

func (b *Builder) System(argv0 string, args ...string) error

System runs the command in the directory of the builder

type Option

type Option func(*Builder) error

Option represents a With* option for the New method

func WithCommit

func WithCommit(c string) Option

WithCommit specifies the commit we're building (if not used, defaults to "latest".

func WithEnv

func WithEnv(env ...string) Option

WithEnv appends the environment env to the OS environment for each call of an external command.

func WithEnvMap

func WithEnvMap(env map[string]string) Option

WithEnvMap appends the environment env to the OS environment for each call to an external command.

type Result

type Result struct {
	Outfile   string // Outfile is the actual (temporary) file
	Name      string // Name is the suggested base name for the file
	Ext       string // Ext is the suggested file name extension
	BuildInfo *debug.BuildInfo
	Target    target
}

Result represents a single build result

type Targets

type Targets []target

Targets represents a list of os/arch pairs

func (Targets) Match

func (tt Targets) Match(pattern string) iter.Seq[target]

Match is a range iterator returning matching os/arch pairs