elder

Documentation

Overview

Package elder is a wand reference implementation that provides common Mage tasks and stores application configurations and metadata of a project.

The naming is inspired by the "Elder Wand", an extremely powerful wand made of elder wood, from the fantasy novel "Harry Potter". See https://en.wikipedia.org/wiki/Magical_objects_in_Harry_Potter#Elder_Wand for more details.

Index

• Variables
• type Elder
  • func New(opts ...Option) (*Elder, error)
  • func UnwrapCtx(ctx context.Context) (*Elder, error)
  • func (e *Elder) Bootstrap(goModuleImportPaths ...string) []error
  • func (e *Elder) Clean(appName string, opts ...taskFSClean.Option) ([]string, error)
  • func (e *Elder) ExitPrintf(code int, verb nib.Verbosity, format string, args ...interface{})
  • func (e *Elder) GetAppConfig(name string) (app.Config, error)
  • func (e *Elder) GetProjectMetadata() project.Metadata
  • func (e *Elder) GoBuild(appName string, opts ...taskGoBuild.Option) error
  • func (e *Elder) GoModUpgrade(opts ...taskGoModUpgrade.Option) error
  • func (e *Elder) GoTest(appName string, opts ...taskGoTest.Option) error
  • func (e *Elder) Gofumpt(opts ...taskGofumpt.Option) error
  • func (e *Elder) Goimports(opts ...taskGoimports.Option) error
  • func (e *Elder) GolangCILint(opts ...taskGolangCILint.Option) error
  • func (e *Elder) Gox(appName string, opts ...taskGox.Option) error
  • func (e *Elder) RegisterApp(name, displayName, pathRel string) error
  • func (e *Elder) Validate() error
• type Option
  • func WithDisableAutoGenWandDataDir(disableAutoGenWandDataDir bool) Option
  • func WithGoRunnerOptions(opts ...taskGo.RunnerOption) Option
  • func WithGoToolRunnerOptions(opts ...taskGoTool.RunnerOption) Option
  • func WithNib(n nib.Nib) Option
  • func WithProjectOptions(opts ...project.Option) Option
• type Options
  • func NewOptions(opts ...Option) *Options

Variables

var (
	// DefaultGoToolsBinDir is the default directory for compiled executables of Go module-based "main" packages.
	DefaultGoToolsBinDir = filepath.Join(project.DefaultWandCacheDataDir, "tools", "bin")
)

Types

type Elder

type Elder struct {
	nib.Nib
	// contains filtered or unexported fields
}

Elder is a wand.Wand reference implementation that provides common Mage tasks and stores configurations and metadata for applications of a project.

func New

func New(opts ...Option) (*Elder, error)

New creates a new elder wand.

The module name is determined automatically using the "runtime/debug" package. The absolute path to the root directory is automatically set based on the current working directory. When the WithDisableAutoGenWandDataDir option is set to `false` the auto-generation of the directory for wand specific data will be disabled. Note that the working directory must be set manually when the "magefile" is not placed in the root directory by pointing Mage to it:

• "-d <PATH>" option to set the directory from which "magefiles" are read (defaults to ".").
• "-w <PATH>" option to set the working directory where "magefiles" will run (defaults to value of "-d" flag).

If any error occurs it will be of type *cmd.ErrCmd or *project.ErrProject.

References:

1. https://magefile.org/#usage
2. https://golang.org/pkg/os/#Getwd
3. https://golang.org/pkg/runtime/debug/#ReadBuildInfo
4. https://pkg.go.dev/runtime/debug

func UnwrapCtx

func UnwrapCtx(ctx context.Context) (*Elder, error)

UnwrapCtx is a helper function to unwrap a elder wand from context.

func (*Elder) Bootstrap

func (e *Elder) Bootstrap(goModuleImportPaths ...string) []error

Bootstrap runs initialization tasks to ensure the wand is operational and sets up the local development environment by allowing to install executables from Go module-based "main" packages. The paths must be valid Go module import paths, that can optionally include the version suffix, in the "pkg@version" format. See https://pkg.go.dev/github.com/svengreb/wand/pkg/task/gotool for more details about the installation runner. It returns a slice of errors with type *task.ErrRunner containing any error that occurs during the execution.

func (*Elder) Clean

func (e *Elder) Clean(appName string, opts ...taskFSClean.Option) ([]string, error)

Clean is a task to remove filesystem paths, e.g. output data like artifacts and reports from previous development, test, production and distribution builds. It returns paths that have been cleaned along with an error when the task execution fails.

See the "github.com/svengreb/wand/pkg/task/fs/clean" package for all available options.

func (*Elder) ExitPrintf

func (e *Elder) ExitPrintf(code int, verb nib.Verbosity, format string, args ...interface{})

ExitPrintf simplifies the logging for process exits with a suitable verbosity.

References

• https://unix.stackexchange.com/questions/418784/what-is-the-min-and-max-values-of-exit-codes-in-linux

func (*Elder) GetAppConfig

func (e *Elder) GetAppConfig(name string) (app.Config, error)

GetAppConfig returns an application configuration. An empty application configuration is returned along with an error of type *app.ErrApp when there is no configuration in the store for the given name.

func (*Elder) GetProjectMetadata

func (e *Elder) GetProjectMetadata() project.Metadata

GetProjectMetadata returns metadata of the project.

func (*Elder) GoBuild

func (e *Elder) GoBuild(appName string, opts ...taskGoBuild.Option) error

GoBuild is a task for the Go toolchain "build" command. When any error occurs it will be of type *app.ErrApp or *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/golang/build" package for all available options.

func (*Elder) GoModUpgrade

func (e *Elder) GoModUpgrade(opts ...taskGoModUpgrade.Option) error

GoModUpgrade is a task for the "github.com/oligot/go-mod-upgrade" Go module command. "go-mod-upgrade" allows to update outdated Go module dependencies interactively. When any error occurs it will be of type *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/gomodupgrade" package for all available options.

See https://pkg.go.dev/github.com/oligot/go-mod-upgrade for more details about "go-mod-upgrade". The source code of "go-mod-upgrade" is available at https://github.com/oligot/go-mod-upgrade.

func (*Elder) GoTest

func (e *Elder) GoTest(appName string, opts ...taskGoTest.Option) error

GoTest is a task to run the Go toolchain "test" command. The configured output directory for reports like coverage or benchmark profiles will be created recursively when it does not exist yet. When any error occurs it will be of type *app.ErrApp, *task.ErrRunner or os.PathError.

See the "github.com/svengreb/wand/pkg/task/param/golang/test" package for all available options.

func (*Elder) Gofumpt

func (e *Elder) Gofumpt(opts ...taskGofumpt.Option) error

Gofumpt is a task for the "mvdan.cc/gofumpt" Go module command. "gofumpt" enforce a stricter format than "https://pkg.go.dev/cmd/gofmt", while being backwards compatible, and provides additional rules. It is a modified fork of "https://pkg.go.dev/cmd/gofmt" so it can be used as a drop-in replacement. When any error occurs it will be of type *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/gofumpt" package for all available options. See https://github.com/mvdan/gofumpt#added-rules for more details about available rules.

See https://pkg.go.dev/mvdan.cc/gofumpt for more details about "gofumpt". The source code of "gofumpt" is available at https://github.com/mvdan/gofumpt.

func (*Elder) Goimports

func (e *Elder) Goimports(opts ...taskGoimports.Option) error

Goimports is a task for the "golang.org/x/tools/cmd/goimports" Go module command. "goimports" allows to update Go import lines, add missing ones and remove unreferenced ones. It also formats code in the same style as "https://pkg.go.dev/cmd/gofmt" so it can be used as a replacement. When any error occurs it will be of type *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/goimports" package for all available options.

See https://pkg.go.dev/golang.org/x/tools/cmd/goimports for more details about "goimports". The source code of "goimports" is available at https://github.com/golang/tools/tree/master/cmd/goimports.

func (*Elder) GolangCILint

func (e *Elder) GolangCILint(opts ...taskGolangCILint.Option) error

GolangCILint is a task to run the "github.com/golangci/golangci-lint/cmd/golangci-lint" Go module command. "golangci-lint" is a fast, parallel runner for dozens of Go linters Go that uses caching, supports YAML configurations and has integrations with all major IDEs. When any error occurs it will be of type *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/golangcilint" package for all available options.

See https://pkg.go.dev/github.com/golangci/golangci-lint and the official website at https://golangci-lint.run for more details about "golangci-lint". The source code of "golangci-lint" is available at https://github.com/golangci/golangci-lint.

func (*Elder) Gox

func (e *Elder) Gox(appName string, opts ...taskGox.Option) error

Gox is a task to run the "github.com/mitchellh/gox" Go module command. "gox" is a dead simple, no frills Go cross compile tool that behaves a lot like the standard Go toolchain "build" command. When any error occurs it will be of type *app.ErrApp or *task.ErrRunner.

See the "github.com/svengreb/wand/pkg/task/gox" package for all available options.

See https://pkg.go.dev/github.com/mitchellh/gox for more details about "gox". The source code of the "gox" is available at https://github.com/mitchellh/gox.

func (*Elder) RegisterApp

func (e *Elder) RegisterApp(name, displayName, pathRel string) error

RegisterApp creates and stores a new application configuration. Note that the package path must be relative to the project root directory!

It returns an error of type *app.ErrApp when the application path is not relative to the project root directory, when it is not a subdirectory of it or when any other error occurs.

func (*Elder) Validate

func (e *Elder) Validate() error

Validate ensures that the wand is properly initialized and operational. It returns an error of type *task.ErrRunner when the validation of any of the supported task fails.

type Option

type Option func(*Options)

Option is a wand option.

func WithDisableAutoGenWandDataDir

func WithDisableAutoGenWandDataDir(disableAutoGenWandDataDir bool) Option

WithDisableAutoGenWandDataDir indicates whether the auto-generation of the directory for wand specific data should be disabled.

func WithGoRunnerOptions

func WithGoRunnerOptions(opts ...taskGo.RunnerOption) Option

WithGoRunnerOptions sets Go toolchain runner options.

func WithGoToolRunnerOptions

func WithGoToolRunnerOptions(opts ...taskGoTool.RunnerOption) Option

WithGoToolRunnerOptions sets Go module-based tool runner options.

func WithNib

func WithNib(n nib.Nib) Option

WithNib sets the log-level based line printer for human-facing messages.

func WithProjectOptions

func WithProjectOptions(opts ...project.Option) Option

WithProjectOptions sets project options.

type Options

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

Options are wand options.

func NewOptions

func NewOptions(opts ...Option) *Options

NewOptions creates new wand options.