Documentation
¶
Overview ¶
Package version names the version of the running binary — the fact the version pin gate compares against the Repository declaration's pin (§11, ADR-0020) — and, since issue #103, the whole of what `hyper version` prints: the facts a build stamps into a binary, and the page that states them.
The page lives here rather than beside the command because its rules are properties of the facts and not of the surface: a fact the build did not stamp renders `unknown` rather than vanishing, and a commit from a modified tree is marked. Nothing in this package reads a file, an environment variable, or a network; the update check ADR-0019 declined has no half-way house here to grow in.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Version = unknown
Version is the running binary's version — the fact the pin gate compares against the Repository declaration's `version:` for exact equality (§11, ADR-0020, internal/pin).
**It is a `var` because a `const` is the one shape `-ldflags -X` cannot write.** The linker sets a string *variable*; a constant is inlined at compile time and the flag is ignored without complaint, which is why every binary this repository produced before issue #191 reported the same placeholder however it was built. The declaration therefore trades a fact the compiler proves for one the linker asserts, deliberately: nothing reads it in a constant expression — Current builds Facts from it and pin.Check compares it as `binaryVersion` — so what the conversion costs is the guarantee that one binary's answer is fixed at compile time, and what it buys is a version that can be true.
What writes it is one flag, and docs/build/releasing.md states the invocation whole:
go build -ldflags "-X github.com/TheLoomLabs/hyper/internal/version.Version=1.4.0" ./cmd/hyper
Nothing else writes this variable, and nothing reads it from a file, a flag or an environment variable at run time — a version resolved after the build is a fact about the machine rather than about the bytes, and the pin gate compares it as though it were the second (§11, ADR-0014, ADR-0020).
**A build the flag did not reach falls back to the module version, and the default below survives only where that answered nothing either.** Go stamps `Main.Version` from the repository a build's source sat in, Current reads it through stampedVersion, and what is left holding this default is a build with no version from either stamper — a `go test` binary, whose module version is `(devel)` (issue #263). Such a binary reports the same word every fact the build did not supply renders as: `hyper version` prints `hyper unknown`, and the Refusal quoting it reads *this binary is unknown*, which is the honest sentence. It is nobody's release — `hyper project` on such a binary asks for a tag named for it and is answered `404`, which Refuses `release-artefact-absent`, so §11's *an unreleased binary runs and checks and cannot project* arrives as a consequence rather than as a special case.
Functions ¶
This section is empty.
Types ¶
type Facts ¶
type Facts struct {
// Version is what the binary claims to be — the same string the pin
// gate compares and the Refusal quotes as *this binary*.
Version string
// Commit is the VCS revision the build was stamped with (`vcs.revision`).
Commit string
// Built is the VCS time of that revision (`vcs.time`), in RFC 3339.
Built string
// Modified is the build's `vcs.modified` flag: the tree carried edits the
// commit above does not account for.
Modified bool
// Toolchain is the Go version that compiled the binary.
Toolchain string
// OS and Arch are GOOS and GOARCH, the platform the binary was built for.
OS, Arch string
}
Facts is everything `hyper version` states: the binary's own version, the revision and time the build stamped, whether that build came from a modified working tree, the toolchain, and the platform. Every member is a fact about the binary as built, which is why the whole value is passed to the command rather than read inside it — a page assembled from the running build changes with every commit, and a golden file cannot hold one.
An empty string is a fact the build did not stamp, and renders unknown.
func Current ¶
func Current() Facts
Current reads the facts of the running binary out of Go's own build stamping. It is called once, at the entry point, and never from inside the command — which is what makes the command's output deterministic under test.
func (Facts) Page ¶
Page renders the five lines `hyper version` writes to stdout, newline terminated. The first line is the version and nothing else, so a script that wants the bare version cuts one line rather than parsing a document — the accepted cost of `version` taking no `--json` (issue #103). The four below it carry fixed lowercase labels padded to one column.
Source Files