Documentation
¶
Overview ¶
Package binary provides utilities to provision external binaries that can be used as part of automation scripts.
At the core, a binary is a specification indicating the binary name the desired version and an origin pointing at where to obtain the binary from.
Origins implement the logic needed to provision the binary and ensure the version matches expectations. Currently there are only three origins implemented: - GoBinary: provisions binaries by running `go install` - RemoteBinaryDownload: for binaries that can be downloaded directly from a url - RemoteArchiveDownload: for binaries contained in archives that can be downloaded from a url If any other source is needed, a new origin can be implemented by just fulfilling the Origin interface.
Each origin defines its own inputs that are required in order to work. Additionally, the template passed as argument to the Install function will contain all the information regarding the environment this code is running in, to tailor the installation process. e.g. using the GOOS value to point to the correct binary built for the platform.
example usage
// define binary
commitsar, err := binary.New(
"commitsar", // name the binary will have after installation
"0.20.1", // version that will be installed
binary.RemoteArchiveDownload( // the origin is a remote archive for this binary
"https://github.com/aevea/commitsar/releases/download/v{{.Version}}/commitsar_{{.Version}}_{{.GOOS}}_{{.GOARCH}}.tar.gz",
// an archive can contain mutiple files, and here only the binary is needed
// which already has the correct name
map[string]string{"commitsar": "commitsar"},
),
logging.WithLevel(slog.LevelDebug),
)
// ensure the binary is present
// this will download or update the binary if necessary
if err := commitsar.Ensure(); err != nil {
return fmt.Errorf("failed to provision commitsar binary: %w", err)
}
// use via harness
harness.Run(ctx, commitsar.BinPath(), harness.WithArgs("--help"))
// or via os/exec
exec.Command(commitsar.BinPath(), "--help").Run()
Index ¶
Constants ¶
const SkipVersionCheck = ""
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Binary ¶
type Binary struct {
// contains filtered or unexported fields
}
func New ¶
New instantiates a new Binary given a command name, a version and it's Origin. Origins determine where the binary is provisioned from, if it needs installation and how the installation process is handled.
func (*Binary) BinPath ¶
BinPath returns the qualified path to the binary. It's recommended to use this method to obtain the binary command string.
type Option ¶
type Option func(b *Binary)
func WithGOARCHMapping ¶
WithGOARCHMapping allows remapping the value of GOARCH in the template before triggering the installation. This is useful for example in cases where a binary gets distributed as `binname-aarch64` and using the `binname-{{ GOARCH }}` template with the default value would resolve to `binname-arm64` which doesn't exist. The key of the map is the GOARCH value and the value is the wanted replacement; for the case mentioned earlier, pass {"arm64": "aarch64"}.
func WithGOOSMapping ¶
WithGOOSMapping allows remapping the value of GOOS in the template before triggering the installation. This is useful for example in cases where a binary gets distributed as `binname-macos` and using the `binname-{{ GOOS }}` template with the default value would resolve to `binname-darwin` which doesn't exist. The key of the map is the GOOS value and the value is the wanted replacement; for the case mentioned earlier, pass {"darwin": "macos"}.
func WithVersionCmd ¶
WithVersionCmd allows customizing the command that is run to check the version of the binary. The format string should contain a single `%s` placeholder that will be replaced with the binary's command name.
This is useful for binaries that don't support the `--version` flag.
If the format string is SkipVersionCheck, the version check will be disabled.
type Origin ¶
type Origin interface {
// Install performs the installation of a binary.
// The template contains information about the target environment and desired configuration.
Install(template Template) error
}
Origin defines the interface for provisioning binaries from different sources.
func GoBinary ¶
GoBinary creates a new Origin that installs a binary using 'go install' targetting the local bin directory. The pkg parameter should be a package installable using the go cli. e.g. golang.org/x/tools/cmd/goimports
func RemoteArchiveDownload ¶
RemoteArchiveDownload creates a new Origin that downloads and extracts binaries from a compressed archive. The URL can contain template variables that will be resolved using the Template values during installation. e.g. "https://github.com/aevea/commitsar/releases/download/v{{.Version}}/commitsar_{{.Version}}_{{.GOOS}}_{{.GOARCH}}.tar.gz",
The binaries parameter maps archive paths to the desired binary names in the installation directory. Only files specified in this map will be extracted.
func RemoteBinaryDownload ¶
RemoteBinaryDownload creates a new Origin that downloads a binary directly from a URL. The URL can contain template variables that will be resolved using the Template values during installation. e.g. "https://github.com/foo/bar/releases/download/v{{.Version}}/bin_{{.Version}}_{{.GOOS}}_{{.GOARCH}}{{.Extension}}",
type Template ¶
type Template struct {
// GOOS is the operating system target (e.g., "linux", "darwin", "windows")
GOOS string
// GOARCH is the architecture target (e.g., "amd64", "arm64")
GOARCH string
// Directory where the binary is located
Directory string
// Name of the binary
Name string
// Cmd is the command to execute, typically the qualified path to the binary
Cmd string
// Version is the semantic version string
Version string
// Extension is the file extension for the binary.
// Usually it's empty on unix systems and ".exe" on windows.
Extension string
}
Template contains fields used to resolve specific metadata about the binary. It includes system architecture information, binary location details, and version information.
Source Files