Documentation ¶
Index ¶
- Variables
- func SetLogOutput(w io.Writer)
- func SetStepDebug(printDebug bool)
- type AppBuild
- type AppBuildFunc
- type AppPackageFunc
- type AppVariant
- type Build
- func (b *Build) AddStep(step *Step)
- func (b *Build) Benchmark() *Step
- func (b *Build) Build() *Step
- func (b *Build) Execute(args ...string)
- func (b *Build) ExecuteErr(args ...string) (err error)
- func (b *Build) Generate() *Step
- func (b *Build) Graph(verbose bool)
- func (b *Build) Import(prefix string, other *Build)
- func (b *Build) ImportApp(a *AppBuild)
- func (b *Build) Package() *Step
- func (b *Build) Step(name string) *Step
- func (b *Build) StepOk(name string) (*Step, bool)
- func (b *Build) Steps() []string
- func (b *Build) Test() *Step
- func (b *Build) Tools() *Step
- func (b *Build) Workdir(workdir string) *Build
- type Command
- func (i *Command) Arg(args ...string) *Command
- func (i *Command) CaptureStdin() *Command
- func (i *Command) Env(key, value string) *Command
- func (i *Command) OptArg(condition bool, args ...string) *Command
- func (i *Command) Output(w io.Writer) *Command
- func (i *Command) Run(ctx context.Context) error
- func (i *Command) Silent() *Command
- func (i *Command) Stderr(w io.Writer) *Command
- func (i *Command) Stdout(w io.Writer) *Command
- func (i *Command) WorkDir(workdir PathString) *Command
- type GoBuild
- func (b *GoBuild) AddressSanitizer() *GoBuild
- func (b *GoBuild) Arch(arch string) *GoBuild
- func (b *GoBuild) BuildArchive() *GoBuild
- func (b *GoBuild) BuildCArchive() *GoBuild
- func (b *GoBuild) BuildCShared() *GoBuild
- func (b *GoBuild) BuildExe() *GoBuild
- func (b *GoBuild) BuildPie() *GoBuild
- func (b *GoBuild) BuildPlugin() *GoBuild
- func (b *GoBuild) BuildShared() *GoBuild
- func (b *GoBuild) ChangeDir(newDir PathString) *GoBuild
- func (b *GoBuild) DryRun() *GoBuild
- func (b *GoBuild) Env(key, value string) *GoBuild
- func (b *GoBuild) ForceRebuild() *GoBuild
- func (b *GoBuild) GoCompileFlags(flags ...string) *GoBuild
- func (b *GoBuild) LinkerFlags(flags ...string) *GoBuild
- func (b *GoBuild) MemorySanitizer() *GoBuild
- func (b *GoBuild) OS(os string) *GoBuild
- func (b *GoBuild) OutputFilename(filename PathString) *GoBuild
- func (b *GoBuild) PrintCommands() *GoBuild
- func (b *GoBuild) PrintPackages() *GoBuild
- func (b *GoBuild) Private(privateHosts ...string) *GoBuild
- func (b *GoBuild) RaceDetector() *GoBuild
- func (b *GoBuild) Run(ctx context.Context) error
- func (b *GoBuild) SetVariable(pkg, varName, value string) *GoBuild
- func (b *GoBuild) Silent() *GoBuild
- func (b *GoBuild) StripDebugSymbols() *GoBuild
- func (b *GoBuild) Tags(tags ...string) *GoBuild
- func (b *GoBuild) Verbose() *GoBuild
- func (b *GoBuild) Workdir(workdir PathString) *GoBuild
- type GoClean
- type GoTools
- func (g *GoTools) Benchmark(pattern string) *Command
- func (g *GoTools) BenchmarkAll() *Command
- func (g *GoTools) Build(targets ...string) *GoBuild
- func (g *GoTools) Clean() *GoClean
- func (g *GoTools) Command(command string, args ...string) *Command
- func (g *GoTools) Generate(patterns ...string) *Command
- func (g *GoTools) GenerateAll() *Command
- func (g *GoTools) Get(pkg string) *Command
- func (g *GoTools) GetUpdated(pkg string) *Command
- func (g *GoTools) Install(pkg string) *Command
- func (g *GoTools) InvalidateCache()
- func (g *GoTools) ModTidy() *Command
- func (g *GoTools) ModuleName() string
- func (g *GoTools) ModuleRoot() PathString
- func (g *GoTools) Run(target string, args ...string) *Command
- func (g *GoTools) Test(patterns ...string) *Command
- func (g *GoTools) TestAll() *Command
- func (g *GoTools) ToModulePackage(pkg string) string
- func (g *GoTools) ToModulePath(dir string) string
- type PathString
- func (p PathString) Abs() (PathString, error)
- func (p PathString) Base() PathString
- func (p PathString) Chdir() error
- func (p PathString) CopyTo(other PathString) error
- func (p PathString) Create() (*os.File, error)
- func (p PathString) Dir() PathString
- func (p PathString) Exists() bool
- func (p PathString) IsDir() bool
- func (p PathString) IsFile() bool
- func (p PathString) Join(segments ...string) PathString
- func (p PathString) JoinPath(segments ...PathString) PathString
- func (p PathString) Mkdir(mode os.FileMode) error
- func (p PathString) MkdirAll(mode os.FileMode) error
- func (p PathString) Open() (*os.File, error)
- func (p PathString) OpenFile(flag int, mode os.FileMode) (*os.File, error)
- func (p PathString) Rel(other PathString) (PathString, error)
- func (p PathString) Remove() error
- func (p PathString) RemoveAll() error
- func (p PathString) Stat() (os.FileInfo, error)
- func (p PathString) String() string
- func (p PathString) ToSlash() string
- type RunState
- type Runner
- type Step
- func (s *Step) AfterRun(op Runner) *Step
- func (s *Step) BeforeRun(op Runner) *Step
- func (s *Step) Debug(msg string, args ...any)
- func (s *Step) DependsOn(dependency *Step) *Step
- func (s *Step) DependsOnRunner(name, description string, fn Runner) *Step
- func (s *Step) Does(operation Runner) *Step
- func (s *Step) DryRun(ctx context.Context) error
- func (s *Step) Error(msg string, args ...any)
- func (s *Step) Info(msg string, args ...any)
- func (s *Step) Run(ctx context.Context) error
- func (s *Step) Skip() *Step
- func (s *Step) SkipDependencies() *Step
- func (s *Step) UnSkip() *Step
- func (s *Step) Warn(msg string, args ...any)
- type TarArchive
- type Task
- func Chdir(newWorkdir PathString, runner Runner) Task
- func CopyFile(source, target PathString) Task
- func Download(url string, location PathString) Task
- func Error(msg string, args ...any) Task
- func IfError(canErr Runner, handler Runner) Task
- func IfExists(file PathString, r Runner) Task
- func IfNotExists(file PathString, r Runner) Task
- func Mkdir(dir PathString, perm os.FileMode) Task
- func MkdirAll(dir PathString, perm os.FileMode) Task
- func MoveFile(source, target PathString) Task
- func NoOp() Task
- func Plain(fn func()) Task
- func Print(msg string, args ...any) Task
- func RemoveDir(file PathString) Task
- func RemoveFile(file PathString) Task
- func WithoutContext(fn func() error) Task
- func WithoutErr(fn func(context.Context)) Task
- type ZipArchive
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var (
ErrCycleDetected = errors.New("possible dependency cycle detected")
)
Functions ¶
func SetLogOutput ¶
SetLogOutput defines where logs should be written. By default, logs are written to stderr.
func SetStepDebug ¶
func SetStepDebug(printDebug bool)
SetStepDebug sets the global policy on debug step logs.
Types ¶
type AppBuild ¶ added in v0.2.0
type AppBuild struct {
// contains filtered or unexported fields
}
AppBuild is a somewhat opinionated abstraction over the common pattern of building a static executable, including packaging. The build step may be customized as needed, and different OS/Arch variants may be created as needed. Each built executable will be output to ${MODROOT}/build/${APP}_${VARIANT_NAME}/${APP} Default packaging will write a zip or tar.gz to ${MODROOT}/dist/${APP}/${APP}_${VARIANT_NAME}_${VERSION}.(zip|tar.gz) Each variant may override or remove its packaging step.
func NewAppBuild ¶ added in v0.2.0
NewAppBuild creates a new AppBuild with the given details. Empty values are not allowed and will result in a panic. If mainPath is not prefixed with the module name, then it will be added.
func (*AppBuild) Build ¶ added in v0.2.0
func (a *AppBuild) Build(bf AppBuildFunc) *AppBuild
func (*AppBuild) HostVariant ¶ added in v0.2.0
func (a *AppBuild) HostVariant() *AppVariant
HostVariant creates an AppVariant with the current host's GOOS and GOARCH settings. Packaging will be disabled by default for this variant.
func (*AppBuild) NamedVariant ¶ added in v0.2.0
func (a *AppBuild) NamedVariant(variant, os, arch string) *AppVariant
NamedVariant creates an AppVariant much like AppBuild.Variant, but with a custom variant name.
func (*AppBuild) Variant ¶ added in v0.2.0
func (a *AppBuild) Variant(os, arch string) *AppVariant
Variant creates an AppVariant with the given OS and architecture settings.
type AppBuildFunc ¶ added in v0.2.0
type AppBuildFunc func(gb *GoBuild)
AppBuildFunc is a function used to customize an AppBuild or AppVariant's build step.
func (AppBuildFunc) Then ¶ added in v0.2.0
func (bf AppBuildFunc) Then(other AppBuildFunc) AppBuildFunc
type AppPackageFunc ¶ added in v0.2.0
type AppPackageFunc func(binaryPath, destDir PathString, app, variant, version string) Task
AppPackageFunc is a function used to customize an AppVariant's package step.
func PackageTar ¶ added in v0.2.0
func PackageTar() AppPackageFunc
PackageTar will package the binary into a tar.gz. This is the default for non-windows builds.
func PackageZip ¶ added in v0.2.0
func PackageZip() AppPackageFunc
PackageZip will package the binary into a zip. This is the default for windows builds.
func (AppPackageFunc) Then ¶ added in v0.2.0
func (pf AppPackageFunc) Then(other AppPackageFunc) AppPackageFunc
type AppVariant ¶ added in v0.2.0
type AppVariant struct {
// contains filtered or unexported fields
}
AppVariant is a variant of an AppBuild with an OS/Arch specified.
func (*AppVariant) Build ¶ added in v0.2.0
func (v *AppVariant) Build(bf AppBuildFunc) *AppVariant
Build sets the AppBuildFunc specific to this variant. AppBuildFunc.Then may be used to combine multiple build customizations.
func (*AppVariant) NoPackage ¶ added in v0.2.0
func (v *AppVariant) NoPackage() *AppVariant
NoPackage will mark this variant as one that doesn't include a packaging step.
func (*AppVariant) Package ¶ added in v0.2.0
func (v *AppVariant) Package(pf AppPackageFunc) *AppVariant
Package sets the AppPackageFunc specific to this variant. AppPackageFunc.Then may be used to combine multiple package steps.
type Build ¶
type Build struct {
// contains filtered or unexported fields
}
Build is a collection of related Steps. Together, they form the structure and basis for a build pipeline.
func NewBuild ¶
func NewBuild() *Build
NewBuild constructs a new Build with the standard structure. This includes the following steps:
- tools for installing and verifying required tooling.
- generate for code generation.
- test for running unit tests.
- benchmark for running benchmarks. This step will be skipped in Build.Execute by default, unless included with a flag or called for explicitly.
- build for building binaries.
- package for building distributable artifacts.
func (*Build) Execute ¶
Execute executes a Build as configured, as if it were a CLI application. It takes string arguments to allow overriding the default of capturing os.Args. Run this with the -h flag to see usage information. If an error occurs within Execute, then the error will be logged and os.Exit will be called with a non-zero exit code.
Note that the build will attempt to change its working directory to the root of the module, so all filesystem paths should be relative to the root. GoTools.ToModulePath may be useful to adhere to this constraint.
Example ¶
var ( ranTools bool ranGenerate bool ) b := NewBuild() b.Tools().DependsOnRunner("print-tools", "", Task(func(ctx context.Context) error { fmt.Println("Running in tools") return nil })) b.Tools().Does(Task(func(ctx context.Context) error { ranTools = true return nil })) b.Generate().Does(Task(func(ctx context.Context) error { ranGenerate = true return nil })) b.Package().DependsOnRunner("print-pkg", "", Task(func(ctx context.Context) error { fmt.Println("Running in package") return nil })) b.Execute("--skip", "tools", "--skip", "generate", "package", "print-tools") fmt.Println("Ran tools:", ranTools) fmt.Println("Ran generate:", ranGenerate)
Output: Running in tools Running in package Ran tools: false Ran generate: false
func (*Build) ExecuteErr ¶
ExecuteErr executes a Build as configured, as if it were a CLI application, and returns an error if anything goes wrong. It takes string arguments to allow overriding the default of capturing os.Args. Run this with the -h flag to see usage information. If an error occurs within Execute, then the error will be logged and os.Exit will be called with a non-zero exit code.
Note that the build will attempt to change its working directory to the root of the module, so all filesystem paths should be relative to the root. GoTools.ToModulePath may be useful to adhere to this constraint.
func (*Build) Graph ¶
Example ¶
b := NewBuild() b.Tools().DependsOn(NewStep("print-tools", "").Does(Task(func(ctx context.Context) error { fmt.Println("Running in tools") return nil }))) b.Package().DependsOn(NewStep("print-pkg", "").Does(Task(func(ctx context.Context) error { fmt.Println("Running in package") return nil }))) b.Graph(true)
Output: Printing build graph tools - Installs external tools that will be needed later -> print-tools - No description generate - Generates code, possibly using external tools -> tools * test - Runs unit tests on the code base -> generate * benchmark (skip step) - Runs benchmarking on the code base -> test * build - Builds the code base and outputs an artifact -> benchmark (skip step) * package - Bundles one or more built artifacts into one or more distributable packages -> build * -> print-pkg - No description print-pkg * print-tools * * - duplicate reference
func (*Build) Import ¶
Import will import all steps in the given build, with the given prefix applied and a colon separator. No dependencies on the imported steps will be applied to the current build, dependencies must be applied on the parent Build after importing.
This is used to integrate build steps of components in the same go module. For building a separate go module (like a Git submodule, for example), use CallBuild.
func (*Build) ImportApp ¶ added in v0.2.0
ImportApp imports an AppBuild as a new build, attaching its build and package steps as dependencies of the parent build.
func (*Build) Steps ¶
Example ¶
b := NewBuild() b.Execute("-v", "steps")
Output: benchmark - Runs benchmarking on the code base build - Builds the code base and outputs an artifact generate - Generates code, possibly using external tools package - Bundles one or more built artifacts into one or more distributable packages test - Runs unit tests on the code base tools - Installs external tools that will be needed later
type Command ¶
type Command struct {
// contains filtered or unexported fields
}
func CallBuild ¶
func CallBuild(buildFile PathString, args ...string) *Command
CallBuild allows easily referencing and calling another modmake build. os.Chdir will be called with the module root before go-running the build file, so the buildFile parameter should be relative to the module root. This is safe to use with Git submodules because a GoTools instance will be created based on the location of the Modmake build file and the closest module.
CallBuild is preferable over Build.Import for building separate go modules. If you're building a component of the same go module, then use Build.Import.
- buildFile should be the filesystem path to the build that should be executed
- args are flags and steps that should be executed in the build
func (*Command) CaptureStdin ¶
CaptureStdin will make the Command pass os.Stdin to the executed process.
func (*Command) Output ¶ added in v0.1.1
Output will redirect all data written to either stdout or stderr to w.
func (*Command) Silent ¶
Silent will prevent command output.
Example ¶
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() err := Exec("go", "version").Silent().Run(ctx) if err != nil { panic(err) }
Output:
func (*Command) Stderr ¶ added in v0.1.1
Stderr will capture all data written to the Command's stderr stream and write it to w.
func (*Command) Stdout ¶ added in v0.1.1
Stdout will capture all data written to the Command's stdout stream and write it to w.
func (*Command) WorkDir ¶
func (i *Command) WorkDir(workdir PathString) *Command
WorkDir sets the working directory in which to execute the Command.
type GoBuild ¶
type GoBuild struct {
// contains filtered or unexported fields
}
func (*GoBuild) AddressSanitizer ¶
AddressSanitizer will enable interoperation with address sanitizer. Not all build targets are supported.
func (*GoBuild) Arch ¶
Arch will set the CPU architecture for the go build command using the GOARCH environment variable.
func (*GoBuild) BuildArchive ¶
BuildArchive builds listed non-main packages into .a files. Packages named main are ignored.
func (*GoBuild) BuildCArchive ¶
BuildCArchive builds the listed main package, plus all packages it imports, into a C archive file. The only callable symbols will be those functions exported using a cgo //export comment. Requires exactly one main package to be listed.
func (*GoBuild) BuildCShared ¶
BuildCShared builds the listed main package, plus all packages it imports, into a C shared library. The only callable symbols will be those functions exported using a cgo //import comment. Requires exactly one main package to be listed.
func (*GoBuild) BuildExe ¶
BuildExe will build the listed main packages and everything they import into executables. Packages not named main are ignored.
func (*GoBuild) BuildPie ¶
BuildPie will build the listed main packages and everything they import into position independent executables (PIE). Packages not named main are ignored.
func (*GoBuild) BuildPlugin ¶
BuildPlugin builds the listed main packages, plus all packages that they import, into a Go plugin. Packages not named main are ignored. Note that this is not supported on all build targets, and as far as I know, there are still issues today with plugins. Use at your own risk.
func (*GoBuild) BuildShared ¶
BuildShared will combine all the listed non-main packages into a single shared library that will be used when building with the -linkshared option. Packages named main are ignored.
func (*GoBuild) ChangeDir ¶
func (b *GoBuild) ChangeDir(newDir PathString) *GoBuild
ChangeDir will change the working directory from the default to a new location. If an absolute path cannot be derived from newDir, then this function will panic.
func (*GoBuild) ForceRebuild ¶
ForceRebuild will force all source to be recompiled, rather than relying on build cache.
func (*GoBuild) GoCompileFlags ¶
GoCompileFlags sets arguments to pass to each go tool compile invocation.
func (*GoBuild) LinkerFlags ¶
LinkerFlags sets linker flags (ldflags) values for this build.
func (*GoBuild) MemorySanitizer ¶
MemorySanitizer will enable interoperation with memory sanitizer. Not all build targets are supported.
func (*GoBuild) OS ¶
OS sets the target OS for the go build command using the GOOS environment variable.
func (*GoBuild) OutputFilename ¶
func (b *GoBuild) OutputFilename(filename PathString) *GoBuild
OutputFilename specifies the name of the built artifact.
func (*GoBuild) PrintCommands ¶
PrintCommands will print commands as they are executed.
func (*GoBuild) PrintPackages ¶
PrintPackages will print the names of built packages.
func (*GoBuild) Private ¶
Private specifies private hosts that should not go through proxy.golang.org for resolution.
func (*GoBuild) RaceDetector ¶
RaceDetector will enable race detection.
func (*GoBuild) SetVariable ¶
SetVariable sets an ldflag to set a variable at build time. The pkg parameter should be main, or the fully-qualified package name. The variable referenced doesn't have to be exposed (starting with a capital letter).
Examples ¶
It's a little counter-intuitive how this works, but it's based on how the go tools themselves work.
Main package ¶
Given a module named 'example.com/me/myproject', and a package directory named 'build' with go files in package 'main', the pkg parameter should just be 'main'.
Non-main package ¶
Given a module named 'example.com/me/myproject', and a package directory named 'build' with go files in package 'other', the pkg parameter should be 'example.com/me/myproject/build'.
GoTools.ToModulePackage is provided as a convenience to make it easier to create these reference strings.
See this article for more examples.
func (*GoBuild) StripDebugSymbols ¶
StripDebugSymbols will remove debugging information from the built artifact, including file paths from panic output, reducing file size.
func (*GoBuild) Workdir ¶
func (b *GoBuild) Workdir(workdir PathString) *GoBuild
type GoClean ¶
type GoClean struct { *Command // contains filtered or unexported fields }
func (*GoClean) BuildCache ¶
type GoTools ¶
type GoTools struct {
// contains filtered or unexported fields
}
GoTools provides some utility functions for interacting with the go tool chain. To get an instance of GoTools, use the Go function. Upon first invocation, Go will cache filesystem and module details for reference later.
To invalidate this cache, use GoTools.InvalidateCache.
If your build logic needs to cross into another go module, try using CallBuild.
func Go ¶
func Go() *GoTools
Go will retrieve or initialize an instance of GoTools. This indirection is desirable to support caching of tool chain, filesystem, and module details. This function is concurrency safe, and may be called by multiple goroutines if desired.
func (*GoTools) BenchmarkAll ¶
func (*GoTools) GenerateAll ¶
func (*GoTools) GetUpdated ¶
func (*GoTools) InvalidateCache ¶
func (g *GoTools) InvalidateCache()
InvalidateCache will break the instance cache, forcing the next call to Go to scan the filesystem's information again.
func (*GoTools) ModuleName ¶
ModuleName returns the name of the current module as specified in the go.mod.
func (*GoTools) ModuleRoot ¶
func (g *GoTools) ModuleRoot() PathString
ModuleRoot returns a filesystem path to the root of the current module.
func (*GoTools) ToModulePackage ¶
ToModulePackage is specifically provided to construct a package reference for GoBuild.SetVariable by prepending the module name to the package name, separated by '/'. This is not necessary for setting variables in the main package, as 'main' can be used instead.
// When run in a module named 'example.com/me/myproject', this will output 'example.com/me/myproject/other'. Go().ToModulePackage("other")
See GoBuild.SetVariable for more details.
func (*GoTools) ToModulePath ¶
ToModulePath takes a path to a file or directory within the module, relative to the module root, and translates it to a module path. If a path to a file is given, then a module path to the file's parent directory is returned. If ToModulePath is unable to stat the given path, then this function will panic.
For example, given a module name of 'github.com/example/mymodule', and a relative path of 'app/main.go', the module path 'github.com/example/mymodule/app' is returned.
type PathString ¶
type PathString string
PathString is a string that represents a filesystem path.
String inputs to all PathString functions, including Path, is expected to be a filesystem path with forward slash ('/') separators. These will be translated to actual OS filesystem path strings, making them incompatible with module path strings on Windows.
func Getwd ¶
func Getwd() (PathString, error)
Getwd gets the current working directory as a PathString like os.Getwd.
func Path ¶
func Path(path string, segments ...string) PathString
Path creates a new PathString from the input path segments.
func UserHomeDir ¶
func UserHomeDir() (PathString, error)
UserHomeDir will return the current user's home directory as a PathString.
func (PathString) Abs ¶ added in v0.2.1
func (p PathString) Abs() (PathString, error)
Abs attempts to translate the PathString into an absolute path using filepath.Abs.
func (PathString) Base ¶
func (p PathString) Base() PathString
Base calls filepath.Base on the string representation of this PathString, returning the last element of the path. Trailing path separators are removed before extracting the last element. If the path is empty, Base returns ".". If the path consists entirely of separators, Base returns a single separator.
func (PathString) Chdir ¶
func (p PathString) Chdir() error
Chdir changes the current working directory to the named directory like os.Chdir.
func (PathString) CopyTo ¶
func (p PathString) CopyTo(other PathString) error
CopyTo copies the contents of the file referenced by this PathString to the file referenced by other, creating or truncating the file.
func (PathString) Create ¶
func (p PathString) Create() (*os.File, error)
Create will create or truncate the named file like os.Create.
func (PathString) Dir ¶
func (p PathString) Dir() PathString
Dir calls filepath.Dir on the string representation of this PathString, returning all but the last element of the path. After dropping the final element, Dir calls filepath.Clean on the path and trailing slashes are removed. If the path is empty, Dir returns ".". If the path consists entirely of separators, Dir returns a single separator. The returned path does not end in a separator unless it is the root directory.
func (PathString) Exists ¶
func (p PathString) Exists() bool
Exists returns true if the path references an existing file or directory.
func (PathString) IsDir ¶
func (p PathString) IsDir() bool
IsDir returns true if this PathString references an existing directory.
func (PathString) IsFile ¶
func (p PathString) IsFile() bool
IsFile returns true if this PathString references a file that exists, and it is not a directory.
func (PathString) Join ¶
func (p PathString) Join(segments ...string) PathString
Join will append path segments to this PathString and return a new PathString.
func (PathString) JoinPath ¶
func (p PathString) JoinPath(segments ...PathString) PathString
JoinPath will append PathString segments to this PathString and return a new PathString.
func (PathString) Mkdir ¶
func (p PathString) Mkdir(mode os.FileMode) error
Mkdir creates a new directory with the specified name and permissions like os.Mkdir.
func (PathString) MkdirAll ¶
func (p PathString) MkdirAll(mode os.FileMode) error
MkdirAll creates the named directory and any non-existent path in between like os.MkdirAll.
func (PathString) Open ¶
func (p PathString) Open() (*os.File, error)
Open opens the named file for reading like os.Open.
func (PathString) Rel ¶ added in v0.2.1
func (p PathString) Rel(other PathString) (PathString, error)
Rel attempts to construct a relative path to other, with the current PathString as the base, much like filepath.Rel.
func (PathString) Remove ¶
func (p PathString) Remove() error
Remove removes the named file or directory like os.Remove.
func (PathString) RemoveAll ¶
func (p PathString) RemoveAll() error
RemoveAll removes the path and any children it contains like os.RemoveAll.
func (PathString) Stat ¶
func (p PathString) Stat() (os.FileInfo, error)
Stat will return os.FileInfo for the file referenced by this PathString like os.Stat.
func (PathString) String ¶
func (p PathString) String() string
String returns this PathString as a string.
func (PathString) ToSlash ¶
func (p PathString) ToSlash() string
ToSlash will change the PathString to use slash separators if the OS representation is different.
type Runner ¶
type Runner interface { // Run should immediately execute in the current goroutine when called to ensure predictable build semantics. // Run may initiate other goroutines, but they should complete and be cleaned up before Run returns. Run(context.Context) error }
Runner is any type that may be executed.
func ContextAware ¶
ContextAware creates a Runner that wraps the parameter with context handling logic. In the event that the context is done, the context's error is returned. This should not be used if custom context.Context handling is desired.
type Step ¶
type Step struct {
// contains filtered or unexported fields
}
Step is a step in a Build, a consistent fixture that may be invoked. A Step may depend on others to set up pre-conditions that must be done before this Step executes. Additionally, a Step may have actions that take place before and/or after this Step runs.
Operations on a Step will change the underlying logic. The current Step will be returned as a convenience to allow chaining multiple mutations.
func NewStep ¶
NewStep creates a new Step with the given name and description. If no description is given (indicated by an empty string), then the default description "No description" will be assigned. By default, Step.Run will do nothing, have no dependencies, and have no before/after hooks.
func (*Step) AfterRun ¶
AfterRun adds an operation that will execute after this Step. AfterRun operations will happen before any dependent Step.
func (*Step) BeforeRun ¶
BeforeRun adds an operation that will execute before this Step. BeforeRun operations will happen after this Step's dependencies.
func (*Step) Debug ¶
Debug emits log messages that are really only useful for digging deep into how a build step is executing.
func (*Step) DependsOn ¶
DependsOn makes this Step depend on the given Step. The given step must execute successfully for this Step to be executed.
func (*Step) DependsOnRunner ¶
DependsOnRunner wraps the given Runner in a Step using the name and description parameters, and calls DependsOn with it.
func (*Step) Does ¶
Does specifies the operation that should happen as a result of executing this Step.
func (*Step) Info ¶
Info emits informational log messages that are generally useful for user awareness.
func (*Step) Skip ¶
Skip will skip execution of this step, including its before/after hooks. Dependencies will still be executed unless SkipDependencies is executed.
func (*Step) SkipDependencies ¶
SkipDependencies will prevent running dependency Steps for this Step.
type TarArchive ¶
type TarArchive struct {
// contains filtered or unexported fields
}
TarArchive represents a Runner that performs operations on a tar archive that uses gzip compression. The Runner is created with Tar.
func Tar ¶
func Tar(location PathString) *TarArchive
Tar will create a new TarArchive to contextualize follow-on operations that act on a tar.gz file. Adding a ".tar.gz" suffix to the location path string is recommended, but not required.
func (*TarArchive) AddFile ¶
func (t *TarArchive) AddFile(sourcePath PathString) *TarArchive
AddFile adds the referenced file with the same archive path as what is given. The archive path will be converted to slash format.
func (*TarArchive) AddFileWithPath ¶
func (t *TarArchive) AddFileWithPath(sourcePath, archivePath PathString) *TarArchive
AddFileWithPath adds the referenced file with an archive path specified. The archive path will be converted to slash format.
func (*TarArchive) Create ¶
func (t *TarArchive) Create() Task
Create will return a Runner that creates a new tar file with the given files loaded. If a file with the given name already exists, then it will be truncated first. Ensure that all files referenced with AddFile (or AddFileWithPath) and directories exist before running this Runner, because it doesn't try to create them.
func (*TarArchive) Extract ¶
func (t *TarArchive) Extract(extractDir PathString) Task
Extract will extract the named tar archive to the given directory. Any errors encountered while doing so will be immediately returned.
func (*TarArchive) Update ¶
func (t *TarArchive) Update() Task
Update will return a Runner that creates a new tar file with the given files loaded. If a file with the given name already exists, then it will be updated. If a file with the given name does not exist, then this Runner will return an error. Ensure that all files referenced with AddFile (or AddFileWithPath) and directories exist before running this Runner, because it doesn't try to create them.
type Task ¶
Task is a convenient way to make a function that satisfies the Runner interface, and allows for more flexible invocation options.
func Chdir ¶
func Chdir(newWorkdir PathString, runner Runner) Task
Chdir will change the current working directory to newWorkdir and run the Runner in that context. Whether the Runner executes successfully or not, the working directory will be reset back to its original state.
func CopyFile ¶
func CopyFile(source, target PathString) Task
CopyFile creates a Runner that copies a source file to target. The source and target file names are expected to be relative to the build's working directory, unless they are absolute paths. The target file will be created or truncated as appropriate.
func Download ¶
func Download(url string, location PathString) Task
func Error ¶
Error will create a Task returning an error, creating it by passing msg and args to fmt.Errorf.
func IfError ¶
IfError will create a Runner with an error handler Runner that is only executed if the base Runner returns an error. If both the base Runner and the handler return an error, then the handler's error will be returned.
Example ¶
canError := Error("An error occurred!") err := IfError(canError, Print("Error handled")).Run(context.Background()) if err != nil { fmt.Println("Error should not have been returned:", err) }
Output:
func IfExists ¶
func IfExists(file PathString, r Runner) Task
IfExists will execute the Runner if the file exists, returning nil otherwise.
func IfNotExists ¶
func IfNotExists(file PathString, r Runner) Task
IfNotExists will skip executing the Runner if the given file exists, returning nil. This is similar to the default Make behavior of skipping a task if the target file already exists.
func Mkdir ¶
func Mkdir(dir PathString, perm os.FileMode) Task
Mkdir makes a directory named dir, if it doesn't exist already. If the directory already exists, then nothing is done and err will be nil. Any error encountered while making the directory is returned.
func MkdirAll ¶
func MkdirAll(dir PathString, perm os.FileMode) Task
MkdirAll makes the target directory, and any directories in between. Any error encountered while making the directories is returned.
func MoveFile ¶
func MoveFile(source, target PathString) Task
MoveFile creates a Runner that will move the file indicated by source to target. The source and target file names are expected to be relative to the build's working directory, unless they are absolute paths. The target file will be created or truncated as appropriate.
func Plain ¶
func Plain(fn func()) Task
Plain is a convenience function that translates a no-argument, no-return function into a Task, combining the logic of WithoutContext and WithoutErr.
func RemoveDir ¶
func RemoveDir(file PathString) Task
RemoveDir will create a Runner that removes the directory specified and all of its contents from the filesystem. If the directory doesn't exist, then this Runner returns nil. Any other error encountered while removing the directory is returned.
func RemoveFile ¶
func RemoveFile(file PathString) Task
RemoveFile will create a Runner that removes the specified file from the filesystem. If the file doesn't exist, then this Runner returns nil. Any other error encountered while removing the file is returned.
func WithoutContext ¶
WithoutContext is a convenience function that handles the inbound context.Context in cases where it isn't needed. If the context is cancelled when this Task executes, then the context's error will be returned.
func WithoutErr ¶
WithoutErr is a convenience function that allows passing a function that should never return an error and translating it to a Task. The returned Task will recover panics by returning them as errors.
type ZipArchive ¶
type ZipArchive struct {
// contains filtered or unexported fields
}
ZipArchive represents a Runner that performs operations on a tar archive that uses gzip compression. The Runner is created with Zip.
func Zip ¶
func Zip(location PathString) *ZipArchive
Zip will create a new ZipArchive to contextualize follow-on operations that act on a zip file. Adding a ".zip" suffix to the location path string is recommended, but not required.
func (*ZipArchive) AddFile ¶
func (z *ZipArchive) AddFile(sourcePath PathString) *ZipArchive
AddFile adds the referenced file with the same archive path as what is given. The archive path will be converted to slash format.
func (*ZipArchive) AddFileWithPath ¶
func (z *ZipArchive) AddFileWithPath(sourcePath, archivePath PathString) *ZipArchive
AddFileWithPath adds the referenced file with an archive path specified. The archive path will be converted to slash format.
func (*ZipArchive) Create ¶
func (z *ZipArchive) Create() Task
Create will return a Runner that creates a new zip file with the given files loaded. If a file with the given name already exists, then it will be truncated first. Ensure that all files referenced with AddFile (or AddFileWithPath) and directories exist before running this Runner, because it doesn't try to create them.
func (*ZipArchive) Extract ¶
func (z *ZipArchive) Extract(extractDir PathString) Task
Extract will extract the named zip archive to the given directory. Any errors encountered while doing so will be immediately returned.
func (*ZipArchive) Update ¶
func (z *ZipArchive) Update() Task
Update will return a Runner that creates a new zip file with the given files loaded. If a file with the given name already exists, then it will be updated. If a file with the given name does not exist, then this Runner will return an error. Ensure that all files referenced with AddFile (or AddFileWithPath) and directories exist before running this Runner, because it doesn't try to create them.