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

• type Elder
  • func New(opts ...Option) (*Elder, error)
  • func UnwrapCtx(ctx context.Context) (*Elder, error)
  • func (e *Elder) Bootstrap() 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) GoTest(appName string, opts ...taskGoTest.Option) error
  • func (e *Elder) Gofumpt(appName string, opts ...taskGofumpt.Option) error
  • func (e *Elder) Goimports(appName string, opts ...taskGoimports.Option) error
  • func (e *Elder) GolangCILint(appName string, 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 WithGoRunnerOptions(opts ...taskGo.RunnerOption) Option
  • func WithGobinRunnerOptions(opts ...taskGobin.RunnerOption) Option
  • func WithNib(n nib.Nib) Option
  • func WithProjectOptions(opts ...project.Option) Option
• type Options
  • func NewOptions(opts ...Option) *Options

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. 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() error

Bootstrap runs initialization tasks to ensure the wand is operational. If an error occurs it will be of type *task.ErrRunner.

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) 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(appName string, 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.

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(appName string, 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.

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(appName string, 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 *app.ErrApp or *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 all tasks are 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 WithGoRunnerOptions

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

WithGoRunnerOptions sets Go toolchain runner options.

func WithGobinRunnerOptions

func WithGobinRunnerOptions(opts ...taskGobin.RunnerOption) Option

WithGobinRunnerOptions sets "gobin" 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.