spec

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2025 License: MIT Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AlgorithmString added in v0.2.0 

func AlgorithmString(a *Algorithm) string

AlgorithmString converts Algorithm to string

func NamingConventionOSString added in v0.2.0 

func NamingConventionOSString(os *NamingConventionOS) string

NamingConventionOSString converts NamingConventionOS to string

func PlatformArchString added in v0.2.0 

func PlatformArchString(arch *SupportedPlatformArch) string

PlatformArchString converts SupportedPlatformArch to string

func PlatformOSString added in v0.2.0 

func PlatformOSString(os *SupportedPlatformOS) string

PlatformOSString converts SupportedPlatformOS to string

func StringPtr added in v0.2.0 

func StringPtr(s string) *string

StringPtr returns a pointer to the string

func StringPtrOrNil added in v0.2.0 

func StringPtrOrNil(s string) *string

StringPtrOrNil returns a pointer to the string, or nil if the string is empty

func StringValue added in v0.2.0 

func StringValue(s *string) string

StringValue safely dereferences a string pointer

func Validate added in v0.7.2 

func Validate(s *InstallSpec) error

Validate validates all fields in InstallSpec that will be embedded in shell scripts

func ValidateShellSafe added in v0.7.2 

func ValidateShellSafe(value, fieldName string) error

ValidateShellSafe checks if a string is safe to embed in shell scripts

Types

type Algorithm added in v0.2.0 

type Algorithm string

Hash algorithm used for checksums. Must match the algorithm used by the project's checksum files. Most projects use sha256. 

const (
	Md5    Algorithm = "md5"
	Sha1   Algorithm = "sha1"
	Sha256 Algorithm = "sha256"
	Sha512 Algorithm = "sha512"
)

func AlgorithmPtr added in v0.2.0 

func AlgorithmPtr(s string) *Algorithm

AlgorithmPtr converts string to Algorithm pointer

type ArchEmulation 

type ArchEmulation struct {
	// Use amd64 binaries instead of arm64 when Rosetta 2 is available on macOS.
	//
	// Useful when:
	// - arm64 binaries are not available
	// - x86_64 binaries are more stable or feature-complete
	// - You need compatibility with x86_64-only dependencies
	//
	// The installer will detect Rosetta 2 and download amd64 binaries
	// on Apple Silicon Macs when this is enabled.
	Rosetta2 *bool `json:"rosetta2,omitempty"`
}

Architecture emulation configuration

Architecture emulation configuration.

Handles cases where binaries can run on different architectures through emulation layers.

Example: ```yaml arch_emulation: rosetta2: true # Use x86_64 binaries on Apple Silicon Macs ```

type Asset added in v0.2.0 

type Asset struct {
	// Filename template with placeholders.
	//
	// Available placeholders:
	// - ${NAME}: Binary name (from 'name' field or repository name)
	// - ${VERSION}: Version to install (without 'v' prefix, e.g., '1.0.0')
	// - ${TAG}: Original tag with 'v' prefix if present (e.g., 'v1.0.0')
	// - ${OS}: Operating system (e.g., 'linux', 'darwin', 'windows')
	// - ${ARCH}: Architecture (e.g., 'amd64', 'arm64', '386')
	// - ${EXT}: File extension (from 'default_extension' or rules)
	//
	// Examples:
	// - "${NAME}_${VERSION}_${OS}_${ARCH}.tar.gz"
	// - "${NAME}-${VERSION}-${OS}-${ARCH}${EXT}"
	// - "v${VERSION}/${NAME}_${OS}_${ARCH}.zip"
	Template *string `json:"template,omitempty"`
	// Default file extension when not specified in template.
	// This is used when the template contains ${EXT} placeholder.
	// Common values: '.tar.gz', '.zip', '.exe'
	// If not set and template uses ${EXT}, it defaults to empty string.
	DefaultExtension *string `json:"default_extension,omitempty"`
	// Binary names and their paths within the asset.
	//
	// For archives: Specify the path within the extracted directory.
	//
	// If not specified, defaults to a single binary with:
	// - name: The repository name
	// - path: The repository name
	Binaries []BinaryElement `json:"binaries,omitempty"`
	// Platform-specific overrides.
	// Rules are evaluated in order, and ALL matching rules are applied cumulatively.
	// Later rules can override values set by earlier rules.
	// Use this to handle special cases for specific OS/arch combinations.
	Rules []RuleElement `json:"rules,omitempty"`
	// Controls the casing of placeholder values
	NamingConvention *NamingConvention `json:"naming_convention,omitempty"`
	// Architecture emulation configuration
	ArchEmulation *ArchEmulation `json:"arch_emulation,omitempty"`
}

Asset download configuration

Configuration for constructing download URLs and asset names.

The asset configuration determines how to build the download URL for each platform. It uses a template system with placeholders that are replaced with actual values.

type AssetConfig 

type AssetConfig = Asset

type AssetRule 

type AssetRule = RuleElement

type Binary 

type Binary = BinaryElement

type BinaryElement added in v0.2.0 

type BinaryElement struct {
	// Name of the binary to install.
	// This will be the filename created in the installation directory.
	Name *string `json:"name,omitempty"`
	// Path to the binary within the extracted archive.
	//
	// The path relative to the archive root.
	//
	// Examples:
	// - "mytool" - Binary at archive root
	// - "bin/mytool" - Binary in bin subdirectory
	Path *string `json:"path,omitempty"`
}

Binary name and path configuration.

Defines which binary files to install from the downloaded asset. For single binary releases, this is straightforward. For releases with multiple binaries, you can specify which ones to install.

Examples: - Single binary in archive: {name: "mytool", path: "mytool"} - Binary in subdirectory: {name: "mytool", path: "bin/mytool"} - Multiple binaries: [{name: "tool1", path: "tool1"}, {name: "tool2", path: "tool2"}]

type ChecksumConfig 

type ChecksumConfig = Checksums

type Checksums added in v0.2.0 

type Checksums struct {
	// Hash algorithm used for checksums.
	// Must match the algorithm used by the project's checksum files.
	// Most projects use sha256.
	Algorithm *Algorithm `json:"algorithm,omitempty"`
	// Template for checksum filename.
	//
	// If specified, binstaller will download this file to verify checksums.
	// Uses the same placeholders as asset templates.
	//
	// Common patterns:
	// - "${NAME}_${VERSION}_checksums.txt"
	// - "checksums.txt"
	// - "${NAME}-${VERSION}-SHA256SUMS"
	//
	// Leave empty to rely only on embedded checksums.
	Template *string `json:"template,omitempty"`
	// Pre-verified checksums organized by version.
	//
	// Use 'binst embed-checksums' command to automatically populate this.
	// The key is the version string (includes 'v' prefix if present in tag, e.g., 'v1.0.0').
	// The value is an array of filename/hash pairs.
	//
	// This allows offline installation and protects against
	// compromised checksum files.
	EmbeddedChecksums map[string][]EmbeddedChecksumElement `json:"embedded_checksums,omitempty"`
}

Checksum verification configuration

Checksum verification configuration.

Binstaller verifies downloaded files using checksums to ensure integrity. It can either download checksum files from the release or use pre-verified checksums embedded in the configuration.

Example: ```yaml checksums: algorithm: sha256 template: "${NAME}_${VERSION}_checksums.txt" embedded_checksums: "1.0.0": - filename: "mytool_1.0.0_linux_amd64.tar.gz" hash: "abc123..." - filename: "mytool_1.0.0_darwin_amd64.tar.gz" hash: "def456..." ```

type EmbeddedChecksum 

type EmbeddedChecksum = EmbeddedChecksumElement

type EmbeddedChecksumElement added in v0.2.0 

type EmbeddedChecksumElement struct {
	// Asset filename exactly as it appears in the release.
	// This must match the filename generated by the asset template.
	Filename *string `json:"filename,omitempty"`
	// Checksum hash value in hexadecimal format.
	// The format depends on the algorithm specified in ChecksumConfig.
	// For sha256: 64 hex characters, for sha512: 128 hex characters, etc.
	Hash *string `json:"hash,omitempty"`
}

Pre-verified checksum for a specific asset.

Stores the checksum hash for a specific file. These are typically populated using 'binst embed-checksums' command.

Example: ```yaml filename: "mytool_1.0.0_linux_amd64.tar.gz" hash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ```

type InstallSpec 

type InstallSpec struct {
	// Schema version
	Schema *string `json:"schema,omitempty"`
	// Binary name (defaults to repository name if not specified)
	Name *string `json:"name,omitempty"`
	// GitHub repository in format 'owner/repo'
	Repo *string `json:"repo,omitempty"`
	// Default version to install
	DefaultVersion *string `json:"default_version,omitempty"`
	// Default binary installation directory
	DefaultBinDir *string `json:"default_bin_dir,omitempty"`
	// Asset download configuration
	Asset *Asset `json:"asset,omitempty"`
	// Checksum verification configuration
	Checksums *Checksums `json:"checksums,omitempty"`
	// Archive extraction configuration
	Unpack *Unpack `json:"unpack,omitempty"`
	// List of supported OS/architecture combinations
	SupportedPlatforms []SupportedPlatformElement `json:"supported_platforms,omitempty"`
}

Configuration specification for binstaller binary installation.

This is the root configuration that defines how to download, verify, and install binaries from GitHub releases.

Minimal example: ```yaml schema: v1 repo: owner/project asset: template: "${NAME}_${VERSION}_${OS}_${ARCH}.tar.gz" ```

Complete example with all features: ```yaml schema: v1 name: mytool repo: myorg/mytool default_version: latest default_bin_dir: ${HOME}/.local/bin

# Asset configuration with platform-specific rules asset: template: "${NAME}_${VERSION}_${OS}_${ARCH}${EXT}" default_extension: .tar.gz binaries: - name: mytool path: mytool - name: mytool-helper path: bin/mytool-helper rules: # Windows gets .zip extension - when: os: windows ext: .zip # macOS uses different naming - when: os: darwin os: macOS ext: .zip # Special handling for M1 Macs - when: os: darwin arch: arm64 template: "${NAME}_${VERSION}_${OS}_${ARCH}_signed${EXT}" naming_convention: os: lowercase arch_emulation: rosetta2: true

# Security features checksums: algorithm: sha256 template: "${NAME}_${VERSION}_checksums.txt" embedded_checksums: "1.0.0": - filename: "mytool_1.0.0_linux_amd64.tar.gz" hash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

# Archive handling unpack: strip_components: 1

# Platform restrictions supported_platforms: - os: linux arch: amd64 - os: linux arch: arm64 - os: darwin arch: amd64 - os: darwin arch: arm64 - os: windows arch: amd64 ```

func UnmarshalInstallSpec added in v0.2.0 

func UnmarshalInstallSpec(data []byte) (InstallSpec, error)

func (*InstallSpec) Marshal added in v0.2.0 

func (r *InstallSpec) Marshal() ([]byte, error)

func (*InstallSpec) SetDefaults 

func (s *InstallSpec) SetDefaults()

SetDefaults sets default values for the InstallSpec

type NamingConvention 

type NamingConvention struct {
	// Casing for ${OS} placeholder.
	//
	// - lowercase (default): "linux", "darwin", "windows"
	// - titlecase: "Linux", "Darwin", "Windows"
	OS *NamingConventionOS `json:"os,omitempty"`
	// Casing for ${ARCH} placeholder.
	//
	// Currently only supports lowercase.
	// Values like "amd64", "arm64", "386".
	Arch *NamingConventionArch `json:"arch,omitempty"`
}

Controls the casing of placeholder values

Controls the casing of template placeholders.

Some projects use different casing conventions in their release filenames. This provides a simpler alternative to using rules for common cases like titlecase OS names.

Example: ```yaml naming_convention: os: titlecase # "Darwin" instead of "darwin" arch: lowercase # "amd64" (default) ```

type NamingConventionArch added in v0.2.0 

type NamingConventionArch string
const (
	ArchLowercase NamingConventionArch = "lowercase"
)

type NamingConventionOS added in v0.2.0 

type NamingConventionOS string

Casing for ${OS} placeholder.

- lowercase (default): "linux", "darwin", "windows" - titlecase: "Linux", "Darwin", "Windows" 

const (
	OSLowercase NamingConventionOS = "lowercase"
	Titlecase   NamingConventionOS = "titlecase"
)

func NamingConventionOSPtr added in v0.2.0 

func NamingConventionOSPtr(s string) *NamingConventionOS

NamingConventionOSPtr converts string to NamingConventionOS pointer

type Platform 

type Platform = SupportedPlatformElement

Type aliases for backward compatibility

type PlatformCondition 

type PlatformCondition = When

type RuleElement added in v0.2.0 

type RuleElement struct {
	// Condition for applying this rule.
	// All specified fields must match for the rule to apply.
	// If a field is not specified, it matches any value.
	When *When `json:"when,omitempty"`
	// Override template for matching platforms.
	// This completely replaces the default template when the rule matches.
	Template *string `json:"template,omitempty"`
	// Override OS value for matching platforms.
	// This changes the ${OS} placeholder value in the template.
	// Useful when the release uses different OS naming (e.g., 'mac' instead of 'darwin').
	OS *string `json:"os,omitempty"`
	// Override architecture value for matching platforms.
	// This changes the ${ARCH} placeholder value in the template.
	// Useful when the release uses different arch naming (e.g., 'x64' instead of 'amd64').
	Arch *string `json:"arch,omitempty"`
	// Override extension for matching platforms.
	// This changes the ${EXT} placeholder value in the template.
	// Common values: '.tar.gz', '.zip', '.exe'
	EXT *string `json:"ext,omitempty"`
	// Override binary configuration for matching platforms.
	// This replaces the default binary configuration when the rule matches.
	// Useful when different platforms have different binary names or paths.
	Binaries []BinaryElement `json:"binaries,omitempty"`
}

Platform-specific asset configuration override.

Rules are evaluated in order, and ALL matching rules are applied sequentially. Each matching rule's overrides are applied cumulatively, with later rules overriding values set by earlier rules.

A rule matches when all specified conditions in 'when' are met.

Example: ```yaml rules: # Rule 1: Windows gets .zip extension - when: os: windows ext: .zip

# Rule 2: Darwin is renamed to macOS - when: os: darwin os: macOS

# Rule 3: Darwin also gets .zip (cumulative with rule 2) - when: os: darwin ext: .zip

# Rule 4: Darwin arm64 gets special template (cumulative with rules 2 & 3) - when: os: darwin arch: arm64 template: "${NAME}_${VERSION}_${OS}_${ARCH}_signed${EXT}" ```

In this example, for darwin/arm64: - Rule 2 changes OS to "macOS" - Rule 3 changes extension to ".zip" - Rule 4 changes the entire template - Final result uses all these changes

func (*RuleElement) GetExt added in v0.2.0 

func (r *RuleElement) GetExt() *string

Helper function to get Ext field (generated code uses EXT)

func (*RuleElement) SetExt added in v0.2.0 

func (r *RuleElement) SetExt(ext *string)

Helper function to set Ext field

type SupportedPlatformArch added in v0.2.0 

type SupportedPlatformArch string

CPU architecture identifier.

Values are based on Go's GOARCH (runtime.GOARCH) and compatible with shlib's uname_arch.sh: https://github.com/client9/shlib/blob/master/uname_arch_check.sh

Common values: - "amd64" (x86_64) - 64-bit x86 - "arm64" (aarch64) - 64-bit ARM - "386" (i386) - 32-bit x86 - "arm" - 32-bit ARM (base)

ARM variants with version: - "armv5" - ARM v5 - "armv6" - ARM v6 (e.g., Raspberry Pi 1) - "armv7" - ARM v7 (e.g., Raspberry Pi 2)

Less common: - "ppc64", "ppc64le" - PowerPC 64-bit - "mips", "mipsle", "mips64", "mips64le" - MIPS architectures - "s390x" - IBM Z architecture - "riscv64" - RISC-V 64-bit - "loong64" - LoongArch 64-bit - "wasm" - WebAssembly - "amd64p32" - AMD64 with 32-bit pointers 

const (
	Amd64    SupportedPlatformArch = "amd64"
	Amd64P32 SupportedPlatformArch = "amd64p32"
	Arm      SupportedPlatformArch = "arm"
	Arm64    SupportedPlatformArch = "arm64"
	Armv5    SupportedPlatformArch = "armv5"
	Armv6    SupportedPlatformArch = "armv6"
	Armv7    SupportedPlatformArch = "armv7"
	Loong64  SupportedPlatformArch = "loong64"
	MIPS     SupportedPlatformArch = "mips"
	Mips64   SupportedPlatformArch = "mips64"
	Mips64LE SupportedPlatformArch = "mips64le"
	Mipsle   SupportedPlatformArch = "mipsle"
	Ppc64    SupportedPlatformArch = "ppc64"
	Ppc64LE  SupportedPlatformArch = "ppc64le"
	Riscv64  SupportedPlatformArch = "riscv64"
	S390X    SupportedPlatformArch = "s390x"
	The386   SupportedPlatformArch = "386"
	WASM     SupportedPlatformArch = "wasm"
)

func SupportedPlatformArchPtr added in v0.3.0 

func SupportedPlatformArchPtr(s string) *SupportedPlatformArch

SupportedPlatformArchPtr converts string to SupportedPlatformArch pointer

type SupportedPlatformElement added in v0.2.0 

type SupportedPlatformElement struct {
	// Operating system identifier.
	//
	// Values are based on Go's GOOS (runtime.GOOS) and compatible with
	// shlib's uname_os.sh: https://github.com/client9/shlib/blob/master/uname_os.sh
	//
	// Common values:
	// - "linux" - Linux distributions
	// - "darwin" - macOS
	// - "windows" - Windows
	// - "freebsd", "openbsd", "netbsd" - BSD variants
	// - "android" - Android
	//
	// Full list from go tool dist list:
	OS *SupportedPlatformOS `json:"os,omitempty"`
	// CPU architecture identifier.
	//
	// Values are based on Go's GOARCH (runtime.GOARCH) and compatible with
	// shlib's uname_arch.sh: https://github.com/client9/shlib/blob/master/uname_arch_check.sh
	//
	// Common values:
	// - "amd64" (x86_64) - 64-bit x86
	// - "arm64" (aarch64) - 64-bit ARM
	// - "386" (i386) - 32-bit x86
	// - "arm" - 32-bit ARM (base)
	//
	// ARM variants with version:
	// - "armv5" - ARM v5
	// - "armv6" - ARM v6 (e.g., Raspberry Pi 1)
	// - "armv7" - ARM v7 (e.g., Raspberry Pi 2)
	//
	// Less common:
	// - "ppc64", "ppc64le" - PowerPC 64-bit
	// - "mips", "mipsle", "mips64", "mips64le" - MIPS architectures
	// - "s390x" - IBM Z architecture
	// - "riscv64" - RISC-V 64-bit
	// - "loong64" - LoongArch 64-bit
	// - "wasm" - WebAssembly
	// - "amd64p32" - AMD64 with 32-bit pointers
	Arch *SupportedPlatformArch `json:"arch,omitempty"`
}

Supported OS and architecture combination.

Defines a specific platform that the binary supports. Used to restrict installation to known-working platforms.

Example: ```yaml supported_platforms: - os: linux arch: amd64 - os: linux arch: arm64 - os: darwin arch: amd64 - os: darwin arch: arm64 - os: windows arch: amd64 ```

type SupportedPlatformOS added in v0.2.0 

type SupportedPlatformOS string

Operating system identifier.

Values are based on Go's GOOS (runtime.GOOS) and compatible with shlib's uname_os.sh: https://github.com/client9/shlib/blob/master/uname_os.sh

Common values: - "linux" - Linux distributions - "darwin" - macOS - "windows" - Windows - "freebsd", "openbsd", "netbsd" - BSD variants - "android" - Android

Full list from go tool dist list: 

const (
	AIX       SupportedPlatformOS = "aix"
	Android   SupportedPlatformOS = "android"
	Darwin    SupportedPlatformOS = "darwin"
	Dragonfly SupportedPlatformOS = "dragonfly"
	Freebsd   SupportedPlatformOS = "freebsd"
	Illumos   SupportedPlatformOS = "illumos"
	Ios       SupportedPlatformOS = "ios"
	JS        SupportedPlatformOS = "js"
	Linux     SupportedPlatformOS = "linux"
	Netbsd    SupportedPlatformOS = "netbsd"
	Openbsd   SupportedPlatformOS = "openbsd"
	Plan9     SupportedPlatformOS = "plan9"
	Solaris   SupportedPlatformOS = "solaris"
	Wasip1    SupportedPlatformOS = "wasip1"
	Windows   SupportedPlatformOS = "windows"
)

func SupportedPlatformOSPtr added in v0.3.0 

func SupportedPlatformOSPtr(s string) *SupportedPlatformOS

SupportedPlatformOSPtr converts string to SupportedPlatformOS pointer

type Unpack added in v0.2.0 

type Unpack struct {
	// Number of leading path components to strip when extracting.
	//
	// Similar to tar's --strip-components option.
	// Useful when archives have an extra top-level directory.
	//
	// Examples:
	// - 0 (default): Extract as-is
	// - 1: Remove first directory level (e.g., "mytool-v1.0.0/bin/mytool" → "bin/mytool")
	// - 2: Remove first two directory levels
	StripComponents *int64 `json:"strip_components,omitempty"`
}

Archive extraction configuration

Archive extraction configuration.

Controls how archives are extracted during installation. Primarily used to handle archives with unnecessary directory nesting.

Example: ```yaml # Archive structure: mytool-v1.0.0/bin/mytool # We want just: bin/mytool unpack: strip_components: 1 ```

type UnpackConfig 

type UnpackConfig = Unpack

type When added in v0.2.0 

type When struct {
	// Match specific operating system.
	//
	// If specified, the rule only applies when the runtime OS matches.
	// If omitted, the rule matches any OS.
	//
	// Can be any string value to support custom OS identifiers.
	// See Platform.os for common values.
	OS *string `json:"os,omitempty"`
	// Match specific architecture.
	//
	// If specified, the rule only applies when the runtime architecture matches.
	// If omitted, the rule matches any architecture.
	//
	// Can be any string value to support custom architecture identifiers.
	// See Platform.arch for common values.
	Arch *string `json:"arch,omitempty"`
}

Condition for applying this rule. All specified fields must match for the rule to apply. If a field is not specified, it matches any value.

Condition for matching specific platforms in rules.

Used in the 'when' clause of asset rules to specify which platforms the rule should apply to. Note that matching uses the original OS and architecture values, not any overridden values from previous rules.

Example: ```yaml when: os: darwin arch: arm64 ```

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.