build

README

go-build

go-build is a library containing common build commands for Go libraries, based on goyek. While the tasks are primarily to satisfy build requirements for CurioSwitch, they are intended to be generally useful so if you'd like, give them a try.

Features

The defined tasks attempt to be a baseline that is useful for any Go repository. One key point is the word "repository", meaning the focus is not only Go code but any file we would typically see with it in a project. This means that format and lint tasks target the following languages:

• Go
• Markdown
• Shell-like, including Dockerfile (files supported by mvdan-sh)
• YAML
• GitHub Actions

All supporting tasks are executed with go run - this means that all languages can be processed with only a single tool dependency, Go itself. Programs like prettier are invoked using wasilibs to achieve this.

Note that the goyek default of non-verbose output is overridden since it seems generally better to have verbose output. -v=false should be passed to a build command to disable verbose output.

Usage

The simplest way to use this library is to copy the contents of build from this repository, which itself is using the defined tasks. You can add it to a Go workspace to keep build-specific libraries like goyek out of your standard modules file, or remove the go.mod / go.sum files to include it as a normal package.

Using the folder build is a goyek convention, but any folder name will work, i.e. if you already use build for transient artifacts. Note that these tasks use out for transient artifacts by default but can be configured for different paths.

A list of all tasks can be seen with go run ./build -h. The commonly used tasks will likely be:

• go run ./build check - executes all code checks, including lint and unit tests. This should be the command run from a CI script.

• go run ./build format - executes all auto-formatting.

Note that for formatting Go code, currently the only tool that is run is golangci-lint with autofixes enabled. It is recommended to configure your .golangci.yml file with the gofumpt and gci linters - this way, both will be applied when running format and checked when running lint.

VSCode users may want to create a workspace configuration similar to ours, which is set to allow IDE auto-save to match the result of the tasks in this project as much as possible.

Documentation

Index

• func DefineTasks(opts ...Option)
• func RegisterFormatTask(task *goyek.DefinedTask)
• func RegisterGenerateTask(task *goyek.DefinedTask)
• func RegisterLintTask(task *goyek.DefinedTask)
• func RegisterTestTask(task *goyek.DefinedTask)
• type Option
  • func ArtifactsPath(path string) Option
  • func ExcludeTasks(task ...string) Option
  • func Tags(tags ...string) Option
  • func VersionActionlint(version string) Option
  • func VersionGoPrettier(version string) Option
  • func VersionGoShellcheck(version string) Option
  • func VersionGoYamllint(version string) Option
  • func VersionGolangCILint(version string) Option

Functions

func DefineTasks

func DefineTasks(opts ...Option)

DefineTasks defines common tasks for Go projects.

func RegisterFormatTask

func RegisterFormatTask(task *goyek.DefinedTask)

RegisterFormatTask adds a task that should be run during the format command.

func RegisterGenerateTask

func RegisterGenerateTask(task *goyek.DefinedTask)

RegisterGenerateTask adds a task that should be run during the generate command.

func RegisterLintTask

func RegisterLintTask(task *goyek.DefinedTask)

RegisterLintTask adds a task that should be run during the lint command.

func RegisterTestTask

func RegisterTestTask(task *goyek.DefinedTask)

RegisterTestTask adds a task that should be run during the test command.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is a configuration option for DefineTasks.

func ArtifactsPath

func ArtifactsPath(path string) Option

ArtifactPath returns an Option to indicate the path to write temporary build artifacts to, for example coverage reports. If not provided, the default is "out".

func ExcludeTasks

func ExcludeTasks(task ...string) Option

ExcludeTasks returns an Option to exclude tasks normally added by default. This can be used to avoid unneeded tasks, for example to disable linting of Markdown while still keeping the ability to manually autoformat it, or to redefine a task with a different implementation.

func Tags

func Tags(tags ...string) Option

Tags returns an Option to add build tags to Go lint tasks. If any code is guarded by a build tag from default compilation, it should be added here to ensure it is linted.

func VersionActionlint

func VersionActionlint(version string) Option

VersionActionlint returns an Option to set the version of actionlint to use. If unset, a default version is used which may not be the latest.

func VersionGoPrettier

func VersionGoPrettier(version string) Option

VersionGoPrettier returns an Option to set the version of go-prettier to use. If unset, a default version is used which may not be the latest.

func VersionGoShellcheck

func VersionGoShellcheck(version string) Option

VersionGoShellcheck returns an Option to set the version of go-shellcheck to use. If unset, a default version is used which may not be the latest.

func VersionGoYamllint

func VersionGoYamllint(version string) Option

VersionGoYamllint returns an Option to set the version of go-yamllint to use. If unset, a default version is used which may not be the latest.

func VersionGolangCILint

func VersionGolangCILint(version string) Option

VersionGolangCILint returns an Option to set the version of golangci-lint to use. If unset, a default version is used which may not be the latest.