golang

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2022 License: MIT Imports: 10 Imported by: 1

Documentation

Overview

Package golang provides Go toolchain tasks and runner.

See https://golang.org/cmd/go for more details.

Index

Constants

View Source 
const (
	// DefaultEnvVarGO111MODULE is the default environment variable name to toggle the Go 1.11 module mode.
	DefaultEnvVarGO111MODULE = "GO111MODULE"

	// DefaultEnvVarGOBIN is the default environment variable name for the Go binary executable search path.
	DefaultEnvVarGOBIN = "GOBIN"

	// DefaultEnvVarGOFLAGS is the default environment variable name for Go tool flags.
	DefaultEnvVarGOFLAGS = "GOFLAGS"

	// DefaultEnvVarGOPATH is the default environment variable name for the Go path.
	DefaultEnvVarGOPATH = "GOPATH"

	// DefaultGOBINSubDirName is the default name of the subdirectory for the Go executables within DefaultEnvVarGOBIN.
	DefaultGOBINSubDirName = "bin"

	// RunnerName is the name of the runner.
	RunnerName = "golang"
)

Variables

View Source 
var DefaultRunnerExec = mg.GoCmd()

DefaultRunnerExec is the default path to the runner executable.

Functions

func BuildGoOptions 

func BuildGoOptions(opts ...Option) []string

BuildGoOptions builds shared Go toolchain options.

Types

type MixinImproveDebugging 

type MixinImproveDebugging struct{}

MixinImproveDebugging is a task.Mixin for golang.Options to add linker flags to improve the debugging of binary artifacts. This includes the disabling of inlining and all compiler optimizations to improve the compatibility for debuggers.

Note that this mixin adds the "all" prefix for "-gcflags" parameters to make sure all packages are affected. If you disabled the "all" prefix on purpose you need to handle this conflict on your own, e.g. by creating more than one binary artifact each with different build options.

See `go help build` and `go tool compile -help` for the documentation of supported flags.

References

func (MixinImproveDebugging) Apply 

func (m MixinImproveDebugging) Apply(so task.Options) (task.Options, error)

Apply applies the mixin to the task options.

type MixinImproveEscapeAnalysis 

type MixinImproveEscapeAnalysis struct{}

MixinImproveEscapeAnalysis is a task.Mixin for golang.Options to add linker flags to improve the escape analysis of binary artifacts. Enables 2/4 level for reporting verbosity, higher levels are too noisy and rarely necessary.

Note that this mixin removes the "all" prefix for "-gcflags" parameters to make sure only the target package is affected, otherwise reports for (traverse) dependencies would be included as well. If you enabled the "all" prefix on purpose you need to handle this conflict on your own, e.g. by creating more than one binary artifact each with different build options.

See `go help build` and `go tool compile -help` for the documentation of supported flags.

References

func (MixinImproveEscapeAnalysis) Apply 

func (m MixinImproveEscapeAnalysis) Apply(so task.Options) (task.Options, error)

Apply applies the mixin to the task options.

type MixinInjectBuildTimeVariableValues 

type MixinInjectBuildTimeVariableValues struct {
	// Data is the map of key/value pairs to inject to variables at build-time.
	// The key must be the path to the variable in form of "<IMPORT_PATH>.<VARIABLE_NAME>",
	// e.g. "pkg/internal/support/app.version".
	// The value is the actual value that will be assigned to the variable, e.g. the application version.
	Data map[string]string

	// GoModule is the identifier of the target Go module to inject the given key/value pairs into.
	GoModule *project.GoModuleID
}

MixinInjectBuildTimeVariableValues is a task.Mixin for golang.Options to inject build-time values through the `-X` linker flags to populate e.g. application metadata variables.

See `go help build`, `go tool compile -help` and the `go` command documentations for more details:

func (MixinInjectBuildTimeVariableValues) Apply 

func (m MixinInjectBuildTimeVariableValues) Apply(so task.Options) (task.Options, error)

Apply applies the mixin to the task options.

type MixinStripDebugMetadata 

type MixinStripDebugMetadata struct{}

MixinStripDebugMetadata is a task.Mixin for golang.Options to add linker flags to strip debug information from binary artifacts. This includes DWARF tables needed for debuggers, but keeps annotations needed for stack traces so panics are still readable. It also shrinks the file size and memory overhead as well as reducing the chance for possible security related problems due to enabled development features or debug information leaks.

See `go tool compile -help` and `go doc cmd/link` for the documentation of supported flags.

See the official Go documentations and other resources for more details:

Note that this mixin adds the "all" prefix for "-gcflags" parameters to make sure all packages are affected If you disabled the "all" prefix on purpose you need to handle this conflict on your own, e.g. by creating more than one binary artifact each with different build options.

See `go help build`, `go tool compile -help` and the `go` command documentations for more details:

A subsequent optimization could be the usage of UPX (https://github.com/upx/upx) to compress the binary artifact afterwards.

func (MixinStripDebugMetadata) Apply 

func (m MixinStripDebugMetadata) Apply(so task.Options) (task.Options, error)

Apply applies the mixin to the task options.

type Option 

type Option func(*Options)

Option is a shared Go toolchain task option.

func WithAsmFlags 

func WithAsmFlags(asmFlags ...string) Option

WithAsmFlags sets flags to pass on each `go tool asm` invocation.

See `go help buildmode`, `go help build` and the `go` command documentations for more details:

func WithEnv 

func WithEnv(env map[string]string) Option

WithEnv sets the runner specific environment.

func WithFlags 

func WithFlags(flags ...string) Option

WithFlags sets additional Go toolchain flags.

See `go help build` and the `go` command documentations for more details:

func WithFlagsPrefixAll 

func WithFlagsPrefixAll(flagsPrefixAll bool) Option

WithFlagsPrefixAll indicates whether the values of `-asmflags` and `-gcflags` should be prefixed with the `all=` pattern in order to apply to all packages. As of Go 1.10 (https://golang.org/doc/go1.10#build), the value specified to `-asmflags` and `-gcflags` are only applied to the current package, therefore the `all=` pattern is used to apply the flag to all packages.

See `go help build` and the `go` command documentations for more details:

func WithGcFlags 

func WithGcFlags(gcFlags ...string) Option

WithGcFlags sets flags to pass on each `go tool compile` invocation.

See `go help buildmode`, `go help build` and the `go` command documentations for more details:

func WithLdFlags 

func WithLdFlags(ldFlags ...string) Option

WithLdFlags sets flags to pass on each `go tool link` invocation.

See `go help buildmode`, `go help build` and the `go` command documentations for more details:

func WithMixins 

func WithMixins(mixins ...task.Mixin) Option

WithMixins sets parameter mixins that can be applied by option consumers.

func WithRaceDetector 

func WithRaceDetector(enableRaceDetector bool) Option

WithRaceDetector indicates whether the race detector should be enabled.

See `go help build` and the `go` command documentations for more details:

func WithTags 

func WithTags(tags ...string) Option

WithTags sets Go toolchain tags.

See `go help build` and the `go` command documentations for more details:

func WithTrimmedPath 

func WithTrimmedPath(enableTrimPath bool) Option

WithTrimmedPath indicates whether all file system paths should be removed from the resulting executable. This is done by adding compiler and linker flags to remove the absolute path to the project root directory from binary artifacts.

See `go help build` and the `go` command documentations for more details:

type Options 

type Options struct {
	// AsmFlags are arguments for the `-asmflags` flag that are passed to each `go tool asm` invocation.
	//
	// See `go help buildmode`, `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	AsmFlags []string

	// EnableRaceDetector indicates whether the race detector should be enabled.
	//
	// See `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	//   - https://golang.org/cmd/go/#hdr-Testing_flags
	EnableRaceDetector bool

	// EnableTrimPath indicates whether all file system paths should be removed from the resulting executable.
	// This is done by adding compiler and linker flags to remove the absolute path to the project root directory from
	// binary artifacts.
	//
	// See `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	//   - https://golang.org/doc/go1.13#go-command
	EnableTrimPath bool

	// Env is the Go toolchain specific environment.
	Env map[string]string

	// Flags are additional flags passed to the `go` command.
	//
	// See `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	Flags []string

	// FlagsPrefixAll indicates whether values of `-asmflags` and `-gcflags` should be prefixed with the `all=`
	// pattern in order to apply to all packages.
	// As of Go 1.10 (https://golang.org/doc/go1.10#build), the value specified to `-asmflags` and `-gcflags` are only
	// applied to the current package, therefore the `all=` pattern is used to apply the flag to all packages.
	//
	// See `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	//   - https://golang.org/doc/go1.10#build
	FlagsPrefixAll bool

	// GcFlags are arguments for the `-gcflags` flag that are passed to each `go tool compile` invocation.
	//
	// See `go help buildmode`, `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Build_modes
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	GcFlags []string

	// LdFlags are arguments for the `-ldflags` flag that are passed to each `go tool link` invocation.
	//
	// See `go help buildmode`, `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Build_modes
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	LdFlags []string

	// Tags are Go tags.
	//
	// See `go help build` and the `go` command documentations for more details:
	//   - https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies
	Tags []string
	// contains filtered or unexported fields
}

Options are shared Go toolchain task options.

References

func NewOptions 

func NewOptions(opts ...Option) *Options

NewOptions creates new shared Go toolchain options.

type Runner 

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

Runner is a task runner for the Go toolchain.

func NewRunner 

func NewRunner(opts ...RunnerOption) *Runner

NewRunner creates a new Go toolchain command runner.

func (*Runner) FilePath 

func (r *Runner) FilePath() string

FilePath returns the path to the runner executable.

func (*Runner) Handles 

func (r *Runner) Handles() task.Kind

Handles returns the supported task kind.

func (*Runner) Run 

func (r *Runner) Run(t task.Task) error

Run runs the command. It returns an error of type *task.ErrRunner when any error occurs during the command execution.

func (*Runner) RunOut added in v0.6.0 

func (r *Runner) RunOut(t task.Task) (string, error)

RunOut runs the command and returns its output. It returns an error of type *task.ErrRunner when any error occurs during the command execution.

func (*Runner) Validate 

func (r *Runner) Validate() error

Validate validates the command executable. It returns an error of type *task.ErrRunner when the executable does not exist and when it is also not available in the executable search path(s) of the current environment.

type RunnerOption 

type RunnerOption func(*RunnerOptions)

RunnerOption is a runner option.

func WithRunnerEnv 

func WithRunnerEnv(env map[string]string) RunnerOption

WithRunnerEnv sets the runner specific environment.

func WithRunnerExec 

func WithRunnerExec(nameOrPath string) RunnerOption

WithRunnerExec sets the name or path of the runner command executable. Defaults to DefaultRunnerExec.

func WithRunnerQuiet 

func WithRunnerQuiet(quiet bool) RunnerOption

WithRunnerQuiet indicates whether the runner output should be minimal.

type RunnerOptions 

type RunnerOptions struct {
	// Env is the runner specific environment.
	Env map[string]string

	// Exec is the name or path of the runner command executable.
	Exec string

	// Quiet indicates whether the runner output should be minimal.
	Quiet bool
}

RunnerOptions are runner options.

func NewRunnerOptions 

func NewRunnerOptions(opts ...RunnerOption) *RunnerOptions

NewRunnerOptions creates new runner options.

Source Files

View all Source files

Directories

Path Synopsis
Package build provides a task for the Go toolchain "build" command.
 Package build provides a task for the Go toolchain "build" command.
Package env provides a task for the Go toolchain `env` command.
 Package env provides a task for the Go toolchain `env` command.
Package install provides a task for the Go toolchain "install" command.
 Package install provides a task for the Go toolchain "install" command.
Package test provides a task for the Go toolchain "test" command.
 Package test provides a task for the Go toolchain "test" command.

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.