magnet

package module
v0.2.6 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2020 License: Apache-2.0 Imports: 21 Imported by: 1

README

magnet

Magnet is a highly experimental library utility library for working with mage as a build toolkit for gravitational projects.

This library mainly combines the moby/buildkit progressui components (ported to avoid vendoring all of buildkit +dependencies) with several helpers for working with docker, golang, http downloads, environment variables etc.

Getting Started

Get started by viewing and running the provided examples

  1. Hello World - A simple getting started example with the UI
  2. Multi Target - Covers multiple build targets, dependencies, and creating a hierarchy of tasks, and downloading upstream assets
  3. Docker - Building and running docker containers
  4. Golang - Building golang based projects

Documentation

Index

Constants

View Source 
const (
	BuildModeArchive  = "archive"
	BuildModeCArchive = "c-archive"
	BuildModeCShared  = "c-shared"
	BuildModeDefault  = "default"
	BuildModeShared   = "shared"
	BuildModeExe      = "exe"
	BuildModePie      = "pie"
	BuildModePlugin   = "plugin"
)
View Source 
const STDERR = 2
View Source 
const STDOUT = 1

Variables

View Source 
var EnvVars map[string]EnvVar
View Source 
var ImportEnvVars map[string]string

Functions

func CmdRan 

func CmdRan(err error) bool

CmdRan examines the error to determine if it was generated as a result of a command running via os/exec.Command. If the error is nil, or the command ran (even if it exited with a non-zero exit code), CmdRan reports true. If the error is an unrecognized type, or it is an error from exec.Command that says the command failed to run (usually due to the command not existing or not being executable), it reports false. based on https://github.com/magefile/mage/blob/310e198ebd9303cd2c876d96e79de954915f60a7/sh/cmd.go#L140

func DefaultBuildDir added in v0.2.0 

func DefaultBuildDir(version string) string

DefaultBuildDir is a default location to place build artifacts at build/<version>.

func DefaultHash added in v0.2.0 

func DefaultHash() string

DefaultHash retrieves the git hash that can be embedded within the binary as build information.

func DefaultLogDir added in v0.2.0 

func DefaultLogDir() string

DefaultLogDir is a default relative path to place logs for this particular build.

func DefaultVersion added in v0.2.0 

func DefaultVersion() string

DefaultVersion generates a default version string from git.

func E 

func E(e EnvVar) string

func ExitStatus 

func ExitStatus(err error) int

ExitStatus returns the exit status of the error if it is an exec.ExitError or if it implements ExitStatus() int. 0 if it is nil or 1 if it is a different error. based on https://github.com/magefile/mage/blob/310e198ebd9303cd2c876d96e79de954915f60a7/sh/cmd.go#L161

func GetEnv 

func GetEnv(key string) string

func InitOutput 

func InitOutput()

func Output 

func Output(ctx context.Context, cmd string, args ...string) (string, error)

Outout runs the provided command, returning the output Note: output / trace won't be present in magnet logs

func Shutdown 

func Shutdown()

Shutdown indicates that the program is exiting, and we should shutdown the progressui 

if it's currently running

Types

type Config added in v0.2.0 

type Config struct {
	LogDir   string
	Version  string
	BuildDir string

	PrintConfig bool
	ModulePath  string
}

func (Config) AbsCacheDir added in v0.2.5 

func (c Config) AbsCacheDir() string

AbsCacheDir is the configured cache directory as an absolute path.

func (Config) CacheDir added in v0.2.5 

func (c Config) CacheDir() string

func (*Config) CheckAndSetDefaults added in v0.2.0 

func (c *Config) CheckAndSetDefaults()

type DockerBindMount added in v0.2.0 

type DockerBindMount struct {
	// Type is the docker type [mount(default), volume, tmpfs]
	// https://docs.docker.com/storage/bind-mounts/
	Type string
	// Source (Bind mount only) is the path to the file or directory on the Docker daemon host.
	Source string
	// Destination is the path where the file or directory is mounted within the container
	Destination string
	// Readonly causes the mount point to be mounted readonly
	Readonly bool
	// BindPropogation changes the bind propagation [rprivate, private, rshared, shared, rslave, slave]
	// https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation
	BindPropogation string
	// Consistency applies to Mac only and is ignored on other platforms. [consistent, delegated, cached]
	Consistency string
}

DockerBindMount represents a mount point that can be passed when running a docker container

type DockerConfigBuild 

type DockerConfigBuild struct {
	DockerConfigCommon
	// Always attempt to pull a newer version of the same image (Default: true)
	Pull bool
	// Compress the build context using gzip (Default: true)
	Compress bool
	// NoCache indicated to docker to avoid caching the results (Default: false)
	NoCache bool
	// Tag Name and optionally a tag in the 'name:tag' format
	Tag []string
	// BuildArgs set build-time variables
	BuildArgs map[string]string
	// Dockerfile is the path to the Dockerfile to build
	Dockerfile string
	// Target sets the target build stage to build
	Target string
	// CacheFrom is a list of images to consider as cache sources
	// https://andrewlock.net/caching-docker-layers-on-serverless-build-hosts-with-multi-stage-builds---target,-and---cache-from/
	CacheFrom []string

	// ContextCopyConfigs is a list of copy operations to build a custom docker context
	ContextCopyConfigs []cp.Config
}

DockerConfigBuild holds configuration for building docker containers.

func (*DockerConfigBuild) AddCacheFrom 

func (m *DockerConfigBuild) AddCacheFrom(from string) *DockerConfigBuild

AddCacheFrom adds an image to consider as a cache source.

func (*DockerConfigBuild) AddTag 

func (m *DockerConfigBuild) AddTag(tag string) *DockerConfigBuild

AddTag adds a name and optionally a tag in the 'name:tag' format. Can be added multiple times.

func (*DockerConfigBuild) Build 

func (m *DockerConfigBuild) Build(ctx context.Context, contextPath string) error

Build calls docker to build a container image.

func (*DockerConfigBuild) CopyToContext added in v0.2.0 

func (m *DockerConfigBuild) CopyToContext(src, dst string, includePatterns, excludePatterns []string) *DockerConfigBuild

CopyToContext creates a new docker context directory structure, including only the files that match the provided glob patterns. Notes: - Can be called multiple times - Destination will be made relative to the root directory of the context automatically - An unset Destination will use the same relative struct as source. Use "/" to copy to the root. - include/exclude patterns are optional, and all files will be copied when unset.

func (*DockerConfigBuild) SetBuildArg 

func (m *DockerConfigBuild) SetBuildArg(key, value string) *DockerConfigBuild

SetBuildArg sets a build argument to pass to the build provess.

func (*DockerConfigBuild) SetCompress 

func (m *DockerConfigBuild) SetCompress(compress bool) *DockerConfigBuild

SetCompress compresses the build context when passing to the docker daemon.

func (*DockerConfigBuild) SetDockerfile 

func (m *DockerConfigBuild) SetDockerfile(dockerfile string) *DockerConfigBuild

SetDockerfile sets the name of the Dockerfile (Default is PATH/Dockerfile).

func (*DockerConfigBuild) SetEnv 

func (m *DockerConfigBuild) SetEnv(key, value string) *DockerConfigBuild

SetEnv sets an environment variable on the docker build command.

func (*DockerConfigBuild) SetEnvs 

func (m *DockerConfigBuild) SetEnvs(envs map[string]string) *DockerConfigBuild

SetEnvs sets environmanet variables on the docker build command.

func (*DockerConfigBuild) SetNoCache 

func (m *DockerConfigBuild) SetNoCache(nocache bool) *DockerConfigBuild

SetNoCache does not use cache when building images.

func (*DockerConfigBuild) SetPull 

func (m *DockerConfigBuild) SetPull(pull bool) *DockerConfigBuild

SetPull attempts to always pull a newer version of base images.

func (*DockerConfigBuild) SetTarget 

func (m *DockerConfigBuild) SetTarget(target string) *DockerConfigBuild

SetTarget sets the target build stage to build.

type DockerConfigCommon 

type DockerConfigCommon struct {

	// Env are environment variables to pass to the spawned docker command
	Env map[string]string
	// contains filtered or unexported fields
}

DockerConfigCommon holds common configuration for docker commands.

type DockerConfigRun 

type DockerConfigRun struct {
	DockerConfigCommon

	// Eun container in background
	Detach bool

	// User ID of spawned process
	UID string
	// Group ID of spawned process
	GID string

	// Privileged Give extended privileges to the container
	Privileged bool
	// ReadOnly mounts the containers root filesystem as read only
	ReadOnly bool
	// Automatically remove the container when it exits
	Remove bool
	// Volumes is a list of volumes to bind mount
	Volumes []DockerBindMount
	// Workdir sets the working directory inside the container
	WorkDir string
}

DockerConfigRun holds configuration used to run a docker container.

func (*DockerConfigRun) AddVolume 

func (m *DockerConfigRun) AddVolume(volume DockerBindMount) *DockerConfigRun

AddVolume attaches a filesystem mount to the container.

func (*DockerConfigRun) Run 

func (m *DockerConfigRun) Run(ctx context.Context, image, cmd string, cargs ...string) error

Run calls docker by cli to run the configured container.

func (*DockerConfigRun) SetDetach 

func (m *DockerConfigRun) SetDetach(detach bool) *DockerConfigRun

SetDetach runs the container in the background.

func (*DockerConfigRun) SetEnv 

func (m *DockerConfigRun) SetEnv(key, value string) *DockerConfigRun

SetEnv passed an environment variable to the running container.

func (*DockerConfigRun) SetEnvs added in v0.2.0 

func (m *DockerConfigRun) SetEnvs(envs map[string]string) *DockerConfigRun

SetEnvs passes environment variables to the running container.

func (*DockerConfigRun) SetGID 

func (m *DockerConfigRun) SetGID(gid string) *DockerConfigRun

SetGID sets the group id of the container.

func (*DockerConfigRun) SetPrivileged 

func (m *DockerConfigRun) SetPrivileged(privileged bool) *DockerConfigRun

SetPrivileged gives extended privileges to the container.

func (*DockerConfigRun) SetReadonly 

func (m *DockerConfigRun) SetReadonly(readonly bool) *DockerConfigRun

SetReadonly sets the containers rootfs to readonly.

func (*DockerConfigRun) SetRemove 

func (m *DockerConfigRun) SetRemove(remove bool) *DockerConfigRun

SetRemove automatically removes the container when the container exits.

func (*DockerConfigRun) SetUID 

func (m *DockerConfigRun) SetUID(uid string) *DockerConfigRun

SetUID sets the user id of the container.

func (*DockerConfigRun) SetWorkDir 

func (m *DockerConfigRun) SetWorkDir(workdir string) *DockerConfigRun

SetWorkDir sets the working directory inside the container.

type DownloadResult added in v0.2.0 

type DownloadResult struct {
}

type EnvVar 

type EnvVar struct {
	Key     string
	Value   string
	Default string
	Short   string
	Long    string
	Secret  bool
}

type ExecConfig 

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

func (*ExecConfig) Run 

func (e *ExecConfig) Run(ctx context.Context, cmd string, args ...string) (bool, error)

Run runs the provided command based on https://github.com/magefile/mage/blob/310e198ebd9303cd2c876d96e79de954915f60a7/sh/cmd.go#L92

func (*ExecConfig) SetEnv 

func (e *ExecConfig) SetEnv(key, value string) *ExecConfig

SetEnv is used to add environment variables to the exec'd commands environment.

func (*ExecConfig) SetEnvs 

func (e *ExecConfig) SetEnvs(env map[string]string) *ExecConfig

SetEnvs is used to add environment variables to the execed commands environment.

func (*ExecConfig) SetWD added in v0.2.0 

func (e *ExecConfig) SetWD(wd string) *ExecConfig

SetWD is used to set the working directory of the command to be executed

type GolangConfigBuild 

type GolangConfigBuild struct {
	GolangConfigCommon

	// Output directory or filename to write resulting build artifacts to
	// Default build/${GOOS}/${GOARCH}/ if GOOS/GOARCH are set
	OutputPath string

	// Remove all filesystem paths from the resulting executable
	TrimPath bool
	// contains filtered or unexported fields
}

func (*GolangConfigBuild) AddGCCGOFlag 

func (m *GolangConfigBuild) AddGCCGOFlag(flag string) *GolangConfigBuild

AddGCCGOFlag adds a flag to pass to the gcc go compiler.

func (*GolangConfigBuild) AddGCFlag 

func (m *GolangConfigBuild) AddGCFlag(flag string) *GolangConfigBuild

AddGCFlag adds a flag to the go tool compile program.

func (*GolangConfigBuild) AddLDFlag 

func (m *GolangConfigBuild) AddLDFlag(flag string) *GolangConfigBuild

AddLDFlag adds an ldflag to pass to the compiler.

func (*GolangConfigBuild) AddLDFlags 

func (m *GolangConfigBuild) AddLDFlags(flags []string) *GolangConfigBuild

AddLDFlags adds multiple ldflags to pass to the compiler.

func (*GolangConfigBuild) AddTag 

func (m *GolangConfigBuild) AddTag(tag string) *GolangConfigBuild

AddTag adds a build tag for the golang compiler to consider during the build.

func (*GolangConfigBuild) Build 

func (m *GolangConfigBuild) Build(ctx context.Context, packages ...string) error

Build executes the build as configured.

func (*GolangConfigBuild) SetBuildContainer 

func (m *GolangConfigBuild) SetBuildContainer(value string) *GolangConfigBuild

SetBuildContainer allows specifying a docker image to use for the build. Instead of running the build toolchain directly, a docker container will be used to map the sources and run the build within the consistent image.

func (*GolangConfigBuild) SetBuildMode 

func (m *GolangConfigBuild) SetBuildMode(mode string) *GolangConfigBuild

SetBuildMode sets the golang build mode (see go help buildmode).

func (*GolangConfigBuild) SetDryRun 

func (m *GolangConfigBuild) SetDryRun(v bool) *GolangConfigBuild

SetDryRun sets the dry-run flag on the go build toolchain.

func (*GolangConfigBuild) SetEnv 

func (m *GolangConfigBuild) SetEnv(key, value string) *GolangConfigBuild

SetEnv sets an environment variable on the build tools.

func (*GolangConfigBuild) SetEnvs 

func (m *GolangConfigBuild) SetEnvs(envs map[string]string) *GolangConfigBuild

SetEnvs allows setting multiple environment variables on the build tools.

func (*GolangConfigBuild) SetGOARCH 

func (m *GolangConfigBuild) SetGOARCH(value string) *GolangConfigBuild

SetGOARCH allows overriding the default architecture for the resulting binary.

func (*GolangConfigBuild) SetGOOS 

func (m *GolangConfigBuild) SetGOOS(value string) *GolangConfigBuild

SetGOOS allows overriding the GOOS env to a specific value.

func (*GolangConfigBuild) SetMod 

func (m *GolangConfigBuild) SetMod(mode string) *GolangConfigBuild

SetMod sets the module download mode (readonly or vendor). Use `go help modules` for more information.

func (*GolangConfigBuild) SetOutputPath 

func (m *GolangConfigBuild) SetOutputPath(path string) *GolangConfigBuild

SetOutputPath sets the output directory or filename to write the resulting build artifacts to Default build/${GOOS}/${GOARCH}/ if GOOS/GOARCH are set.

func (*GolangConfigBuild) SetParallelTasks 

func (m *GolangConfigBuild) SetParallelTasks(p int) *GolangConfigBuild

SetParallelTasks allows overriding the number of parallel tasks the compiler will run (Defaults to number of cores).

func (*GolangConfigBuild) SetRace 

func (m *GolangConfigBuild) SetRace(b bool) *GolangConfigBuild

SetRace indicates whether to enable the race detector.

func (*GolangConfigBuild) SetRebuild 

func (m *GolangConfigBuild) SetRebuild(b bool) *GolangConfigBuild

SetRebuild forces packages that are already up to date to be rebuilt.

func (*GolangConfigBuild) SetTrimpath 

func (m *GolangConfigBuild) SetTrimpath(b bool) *GolangConfigBuild

SetTrimpath removes filesystem paths from the resulting executable.

func (*GolangConfigBuild) SetVerbose 

func (m *GolangConfigBuild) SetVerbose(v bool) *GolangConfigBuild

SetVerbose sets whether to pass verbose flag to go toolchain.

type GolangConfigCommon 

type GolangConfigCommon struct {
	// BuildContainer is the container image to use when running go commands
	BuildContainer string

	// GOOS to pass to the go compiler as an env variable
	GOOS string
	// GOARCH to pass to the go compiler as an env variable
	GOARCH string

	// Env is a set of environment variables to pass to the compiler
	Env map[string]string

	// Rebuilds forces rebuilding of packages that are already up to date
	Rebuild bool

	// Race enables data race detection
	Race bool

	// ParallelTasks is the number of programs, such as build commands or test binaries
	// that can be run in parallel. Defaults to number of CPUs available.
	ParallelTasks *int

	// DryRun print the commands but do not run them
	DryRun bool

	// Verbose prints the name of packages as they are compiled
	Verbose bool

	// BuildMode is the go build mode to use (see go help buildmode)
	BuildMode string

	//GCCGOFlags is a list of arguments to pass on each gccfo compiler/linker invocation
	GCCGOFlags []string

	// GCFlags is a list of arguments to pass on each go tool compile invocation
	GCFlags []string

	// LDFlags is a list of arguments to pass on each go tool link invocation
	LDFlags []string

	// ModMode is the module download mode (readonly or vendor).
	// Use `go help modules` for more information.
	ModMode string

	// Tags is a list of build tags to consider as satisified during the build
	Tags []string
}

type GolangConfigTest 

type GolangConfigTest struct {
	GolangConfigCommon
	// contains filtered or unexported fields
}

func (*GolangConfigTest) AddGCCGOFlag 

func (m *GolangConfigTest) AddGCCGOFlag(flag string) *GolangConfigTest

AddGCCGOFlag adds a flag to pass to the gcc go compiler.

func (*GolangConfigTest) AddGCFlag 

func (m *GolangConfigTest) AddGCFlag(flag string) *GolangConfigTest

AddGCFlag adds a flag to the go tool compile program.

func (*GolangConfigTest) AddLDFlag 

func (m *GolangConfigTest) AddLDFlag(flag string) *GolangConfigTest

AddLDFlag adds an ldflag to pass to the compiler.

func (*GolangConfigTest) AddLDFlags 

func (m *GolangConfigTest) AddLDFlags(flags []string) *GolangConfigTest

AddLDFlags adds multiple ldflags to pass to the compiler.

func (*GolangConfigTest) AddTag 

func (m *GolangConfigTest) AddTag(tag string) *GolangConfigTest

AddTag adds a build tag for the golang compiler to consider during the build.

func (*GolangConfigTest) SetBuildContainer 

func (m *GolangConfigTest) SetBuildContainer(value string) *GolangConfigTest

SetBuildContainer allows specifying a docker image to use for the build. Instead of running the build toolchain directly, a docker container will be used to map the sources and run the build within the consistent image.

func (*GolangConfigTest) SetBuildMode 

func (m *GolangConfigTest) SetBuildMode(mode string) *GolangConfigTest

SetBuildMode sets the golang build mode (see go help buildmode).

func (*GolangConfigTest) SetDryRun 

func (m *GolangConfigTest) SetDryRun(v bool) *GolangConfigTest

SetDryRun sets the dry-run flag on the go build toolchain.

func (*GolangConfigTest) SetEnv 

func (m *GolangConfigTest) SetEnv(key, value string) *GolangConfigTest

SetEnv sets an environment variable on the build tools.

func (*GolangConfigTest) SetEnvs 

func (m *GolangConfigTest) SetEnvs(envs map[string]string) *GolangConfigTest

SetEnvs allows setting multiple environment variables on the build tools.

func (*GolangConfigTest) SetGOARCH 

func (m *GolangConfigTest) SetGOARCH(value string) *GolangConfigTest

SetGOARCH allows overriding the default architecture for the resulting binary.

func (*GolangConfigTest) SetGOOS 

func (m *GolangConfigTest) SetGOOS(value string) *GolangConfigTest

SetGOOS allows overriding the GOOS env to a specific value.

func (*GolangConfigTest) SetMod 

func (m *GolangConfigTest) SetMod(mode string) *GolangConfigTest

SetMod sets the module download mode (readonly or vendor). Use `go help modules` for more information.

func (*GolangConfigTest) SetParallelTasks 

func (m *GolangConfigTest) SetParallelTasks(p int) *GolangConfigTest

SetParallelTasks allows overriding the number of parallel tasks the compiler will run (Defaults to number of cores).

func (*GolangConfigTest) SetRace 

func (m *GolangConfigTest) SetRace(b bool) *GolangConfigTest

SetRace indicates whether to enable the race detector.

func (*GolangConfigTest) SetRebuild 

func (m *GolangConfigTest) SetRebuild(b bool) *GolangConfigTest

SetRebuild forces packages that are already up to date to be rebuilt.

func (*GolangConfigTest) SetVerbose 

func (m *GolangConfigTest) SetVerbose(v bool) *GolangConfigTest

SetVerbose sets whether to pass verbose flag to go toolchain.

func (*GolangConfigTest) Test 

func (m *GolangConfigTest) Test(ctx context.Context, packages ...string) error

Test executes the configured test.

type Magnet 

type Magnet struct {
	Config

	Vertex *progressui.Vertex
	// contains filtered or unexported fields
}

func Root 

func Root(c Config) *Magnet

Root creates a root vertex for executing and capturing status of each build target.

func (*Magnet) Complete 

func (m *Magnet) Complete(err error)

Complete marks the current task as complete.

func (*Magnet) DockerBuild 

func (m *Magnet) DockerBuild() *DockerConfigBuild

DockerBuild creates a command for building a docker container using buildkit.

func (*Magnet) DockerRun 

func (m *Magnet) DockerRun() *DockerConfigRun

DockerRun creates a command builder for running a docker container.

func (*Magnet) Download added in v0.2.0 

func (m *Magnet) Download(url string) (path string, err error)

Download will download a file from a remote URL. It's optimized for working with a local cache, and will send request headers to the upstream server and only download the file if cached or missing from the local cache.

func (*Magnet) DownloadFuture added in v0.2.0 

func (m *Magnet) DownloadFuture(url string) func() (url string, path string, err error)

Download begins a download of a url but doesn't block. Returns a future that when called will block until it can return the path to the file on disk or an error.

func (*Magnet) Exec 

func (m *Magnet) Exec() *ExecConfig

Exec is used to build and run a command on the system.

func (*Magnet) GolangBuild 

func (m *Magnet) GolangBuild() *GolangConfigBuild

GolangBuild returns a builder that can be used to build a golang binary.

func (*Magnet) GolangTest 

func (m *Magnet) GolangTest() *GolangConfigTest

GolangTest returns a builder that can be used to run golang tests against a set of sources.

func (*Magnet) Println 

func (m *Magnet) Println(args ...interface{})

Println allows writing log entries to the log output for the target.

func (*Magnet) Printlnf 

func (m *Magnet) Printlnf(format string, args ...interface{})

Printlnf allows writing log entries to the log output for the target.

func (*Magnet) SetCached added in v0.2.0 

func (m *Magnet) SetCached(cached bool)

SetCached marks the current task as cached when it's completed.

func (*Magnet) Target added in v0.2.0 

func (m *Magnet) Target(name string) *Magnet

type SolveStatusLogger 

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

SolveStatusLogger intercepts SolveStatus messages sent to the progressui, and is able to log the contents to disk for later analysis

Source Files

View all Source files

Directories

Path Synopsis
examples
golang
pkg
cp
progressui

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.