Documentation
¶
Overview ¶
Package buildrun compiles the project's release components and its Go GitHub Actions.
It is the single build engine behind walle (on a laptop) and the build action (in CI): both import it, so an artifact built in CI is built by the same code, with the same flags, as one built locally.
Reproducibility is load-bearing ¶
Every artifact is a pure function of source, Go toolchain version and the injected metadata — never of the machine or the moment. Two consumers depend on that: a deploy tool that diffs asset hashes (CDK, for one) redeploys only what changed, and `walle check actions` can prove a committed action binary matches its source by rebuilding it on a different host and comparing bytes. Hence the fixed flag set in [goBuild]:
- CGO_ENABLED=0 — a static binary, no host C toolchain in the output;
- -trimpath — no absolute host paths;
- -buildvcs=false — no vcs.revision / vcs.modified stamp, which would differ between a clean and a dirty tree and between commits that did not touch the component;
- -ldflags "-s -w" — no symbol table or DWARF: roughly a third smaller, stack traces still work;
- metadata only via -X, and never a timestamp or CI run id.
The package execs `go build` rather than linking the toolchain: there is no library API that compiles and links a binary.
Index ¶
- Constants
- Variables
- func ActionBinary(name string, p Platform) string
- func Actions() ([]string, error)
- func BuildInto(ctx context.Context, component string, p Platform, out, metadata string) error
- func Ldflags(metadata string) string
- func Metadata(ctx context.Context) string
- func SHA256(path string) (string, error)
- type Platform
- type Result
- type Stale
Constants ¶
const ( // BinDir receives host builds: bin/<component>, directly runnable. BinDir = "bin" // ReleaseDir receives cross-compiled release assets: bin/release/<component>-<os>-<arch>. ReleaseDir = "bin/release" // ActionsSrcDir holds one main package per Go GitHub Action: cmd/github-actions/<name>. ActionsSrcDir = "cmd/github-actions" // ActionsDir holds the action definitions: .github/actions/<name>/{action.yaml,index.js,dist/}. ActionsDir = ".github/actions" )
Variables ¶
var ActionPlatforms = []Platform{{"linux", "amd64"}, {"linux", "arm64"}}
ActionPlatforms is what `build actions` cross-compiles each action for. GitHub-hosted Linux runners are amd64 and arm64; add {"darwin", "arm64"} if you run these actions on macOS runners. The shim falls back to building from source on any platform without a binary, so a missing entry costs a compile, not a failure.
Host is the platform walle is running on.
var ReleasePlatforms = []Platform{{"linux", "amd64"}, {"linux", "arm64"}, {"darwin", "arm64"}}
ReleasePlatforms is what `build --all-platforms` cross-compiles for. Each platform is a full compile of the component's closure — cross-compilation shares no cached output across a GOOS/GOARCH boundary — so list only platforms something actually runs on.
Functions ¶
func ActionBinary ¶
ActionBinary is the committed path of an action's binary for a platform. The shim (.github/actions/_shim/shim.js) resolves the same name.
func Actions ¶
Actions lists the Go GitHub Actions by convention: every directory under cmd/github-actions is one, named after the directory, with its definition in .github/actions/<name>. Discovery replaces a hand-kept registry, so there is no list to forget to update.
func BuildInto ¶
BuildInto builds a component for one platform to an explicit path. The determinism check uses it so it exercises exactly the flags the real build uses.
func Ldflags ¶
Ldflags returns the linker flags for an artifact: stripped, with metadata injected into the version package when non-empty.
func Metadata ¶
Metadata returns the build-metadata string (the semver "+build" suffix) for this invocation, in order of precedence:
- BUILD_METADATA, when set — an explicit override, e.g. "release.abc1234";
- in GitHub Actions: "pr<N>.<sha7>" for a pull request (the PR head, not the synthetic merge commit), "main.<sha7>" on main, "branch.<sha7>" otherwise;
- locally: "local.<sha7>", with ".dirty" for an uncommitted tree, or "local.unknown" outside git.
It is one implementation for walle and the build action. It never contains a timestamp or run id: rebuilding the same commit must produce the same bytes.
Types ¶
type Result ¶
Result records one built artifact.
func BuildActions ¶
BuildActions cross-compiles every action for every platform, concurrently. Action binaries carry no metadata: they are committed, and metadata would make every rebuild a diff.
func BuildAll ¶
func BuildAll(ctx context.Context, component, metadata string, platforms []Platform) ([]Result, error)
BuildAll cross-compiles a component for every platform concurrently into bin/release/<name>-<os>-<arch>. Results come back in platform order regardless of completion order, so reports read the same on every run. The group fails fast: the first error cancels the other builds.
type Stale ¶
Stale describes a committed action binary that does not match its source.
func StaleActions ¶
StaleActions rebuilds every committed action binary into a temporary directory and compares bytes. Only binaries present in dist/ are checked, so an action that ships no binaries (source mode) is never stale.
Each rebuild uses the Go toolchain recorded in the committed binary (GOTOOLCHAIN=goX.Y.Z, which the go command downloads once if needed), so a developer on a newer patch release than CI does not produce a false positive.
Source Files