Go Build Helpers

Note: this module requires Go 1.16 or newer.

The packages in this module are designed to reduce boilerplate code when writing build scripts in Go, whether they be Magefiles or just plain Go files run with go run.

The following packages are provided:

• filesystem: provides functionality related to filesystem operations not concisely covered by the Go standard library.

• module: provides functionality for performing code generation and compilation of Go modules. Most of the other helper packages are designed to work with the Module type from this package.

• network: provides functionality for interacting with remote servers and downloading files.

• process: provides functionality for creating and interacting with child processes.

• system: provides functionality and constants related to the underlying operating system.

• tools:

  • tools/protoc: provides functionality for working with the Google protocol buffers compiler.

• validation: provides functionality for validating build step results and working with errors.

Usage examples

Failing when errors are encountered

// +build never

package main

import (
	module "github.com/tensorworks/go-build-helpers/pkg/module"
	validation "github.com/tensorworks/go-build-helpers/pkg/validation"
)

func main() {
	
	// Create a build helper for the Go module in the current working directory
	mod, err := module.ModuleInCwd()
	
	// If an error occurred then log it and exit immediately
	validation.ExitIfError(err)
	
	// Do stuff with the module.Module object here
	// ...
}

Performing code generation

// +build never

package main

import (
	module "github.com/tensorworks/go-build-helpers/pkg/module"
	validation "github.com/tensorworks/go-build-helpers/pkg/validation"
)

func main() {
	
	// Create a build helper for the Go module in the current working directory
	mod, err := module.ModuleInCwd()
	validation.ExitIfError(err)
	
	// Install any Go tools that we require for code generation into our codegen tools directory
	err = mod.InstallGoTools([]string{
		"golang.org/x/tools/cmd/[email protected]",
	})
	validation.ExitIfError(err)
	
	// Run `go generate` with our codegen tools directory appended to the PATH
	err = mod.Generate()
	validation.ExitIfError(err)
}

Building executables

// +build never

package main

import (
	module "github.com/tensorworks/go-build-helpers/pkg/module"
	validation "github.com/tensorworks/go-build-helpers/pkg/validation"
)

func main() {
	
	// Create a build helper for the Go module in the current working directory
	mod, err := module.ModuleInCwd()
	validation.ExitIfError(err)
	
	// Build binaries for any executables in the module (anything with package `main`) for the host GOOS/GOARCH and place them in ./bin
	err = mod.BuildBinariesForHost(module.DefaultBinDir, module.BuildOptions{ Scheme: module.Undecorated })
	validation.ExitIfError(err)
	
	// Alternatively, build binaries for executables using a matrix of GOOS/GOARCH combinations
	err = mod.BuildBinariesForMatrix(
		
		module.DefaultBinDir,
		
		// Note: this produces binaries with suffixed filenames ("cmd/mytool" becomes "bin/mytool-${GOOS}-${GOARCH}${GOEXE}")
		// If you want binaries in subdirectories instead ("cmd/mytool" becomes "bin/${GOOS}/${GOARCH}/mytool${GOEXE}") then use module.PrefixedDirs
		module.BuildOptions{
			Scheme: module.SuffixedFilenames,
		},
		
		module.BuildMatrix{
			
			// This will build binaries for the following GOOS/GOARCH combinations:
			// - darwin/amd64
			// - linux/386
			// - linux/amd64
			// - windows/386
			// - windows/amd64
			
			Platforms: []string{"darwin", "linux", "windows"},
			Architectures: []string{"386", "amd64"},
			Ignore: []string{"darwin/386"},
		},
	)
	validation.ExitIfError(err)
}

Legal

Copyright © 2021, TensorWorks Pty Ltd. Licensed under the MIT License, see the file LICENSE for details.