project

Documentation

Overview

Package project exposes build metadata that the Makefile injects into cascade binaries via -ldflags. Binaries built without ldflags (plain `go install` / `go run`) get a fallback population strategy that keeps the VERSION file as the canonical source for `Version` and uses `runtime/debug.ReadBuildInfo` for git metadata.

Source-of-truth precedence (highest to lowest):

1. -ldflags injection (Makefile builds). Set at link time, before init() runs — so the package vars are non-empty when init() executes, and the fallback below is a no-op.
2. Embedded VERSION file (this package's `init()`, via go:embed). Always populated; ldflags wins only because the var is already set.
3. runtime/debug.ReadBuildInfo (this package's `init()`). Fills git metadata only — never Version.

VERSION file is the *only* source for the `Version` field. ReadBuildInfo's `Main.Version` (a pseudo-version like v0.0.0-...-<sha> or a real semver tag) is never used for `Version` — bumping cascade's version is a one-file edit at project/VERSION. However, when `Main.Version` *is* a pseudo-version, its trailing 12-char commit prefix and 14-digit timestamp are extracted as fallbacks for `GitCommit` and `BuildDate` respectively. This closes the proxy-install gap: a `go install ...@<sha>` built from the Go module proxy (where vcs.* settings are absent) still reports the actual commit.

Modeled on the zylog version-package pattern, adapted to cascade.

Index

• Variables
• func BuildString() string
• func PrintVersions(w io.Writer)
• func VersionString() string

Variables

var (
	// Version is the cascade module version, sourced from project/VERSION.
	// Always populated (either via ldflags or the go:embed fallback).
	Version string

	// GitCommit is the short SHA of the commit the binary was built from.
	// Under the fallback path, this comes from runtime/debug build settings'
	// vcs.revision, truncated to 7 characters and suffixed with "-dirty"
	// when vcs.modified == "true".
	GitCommit string

	// GitBranch is the branch the binary was built from. Populated by
	// ldflags only; Go's build-info doesn't carry branch names, so this
	// stays empty under the fallback path.
	GitBranch string

	// GitSummary is `git describe --tags --dirty --always` output —
	// gives a concise human-readable identifier (e.g. v0.1.0-3-gabc1234).
	// Populated by ldflags only; the fallback path leaves it empty rather
	// than synthesising a substitute that could diverge.
	GitSummary string

	// BuildDate is the RFC3339-formatted UTC build timestamp under the
	// ldflags path. Under the fallback path, it holds the commit time
	// (vcs.time from runtime/debug) — a slight semantic stretch, but the
	// only timestamp signal available without ldflags.
	BuildDate string
)

Build-time metadata. All vars are populated at link time via -ldflags (see Makefile's LDFLAGS_VERSION) for Makefile-built binaries. For plain `go install` / `go run` builds (no ldflags), init() falls back to the embedded VERSION file (Version) and runtime/debug.ReadBuildInfo (GitCommit, BuildDate). GitBranch and GitSummary stay empty under the fallback path — Go's build-info doesn't carry branch names, and a synthesised git-describe could diverge from the Makefile representation.

AP-07 deviation (acknowledged): these are exported package-level **mutable** vars. The substrate's AP-07 ("Mutable Package-Level Globals") is SHOULD-AVOID. Rationale for keeping them: cascade uses them as **link-time injection targets** for `-ldflags -X`, populated once before init() runs and never mutated thereafter in production. They are the standard Go pattern for build-info embedding (also seen in `kubectl`, `hugo`, every cobra-based CLI). AP-07's hazards (order-dependent tests, multi-tenancy collisions) don't apply because these aren't config or registries — they're constants whose value is set at link time. Tests in this package and `internal/cli/cli_test.go` do mutate them (via the withMetadata helper in version_test.go); the "do not call t.Parallel() in any test that mutates these" discipline is documented in S-2 of docs/dev/0014-go-quality-audit.md and at the top of every seam-using *_test.go file.

Functions

func BuildString

func BuildString() string

BuildString returns "<branch>@<commit>, <date>" if GitCommit is set, else "N/A". GitCommit is the canary because a binary built without any ldflags or VCS info has all build-metadata fields empty; if GitCommit is set, the others were either injected by ldflags or populated from ReadBuildInfo.

func PrintVersions

func PrintVersions(w io.Writer)

PrintVersions writes a multi-line block of version info to w, suitable for verbose --version output. Single-line callers should compose VersionString and BuildString directly.

func VersionString

func VersionString() string

VersionString returns Version if set, else "N/A". With the embedded VERSION file fallback, "N/A" is reachable only when tests deliberately zero the package vars; production binaries always have Version populated.