Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0060: Build releases with Zig and preserve target aliases

Status: accepted | Date: 2026-07-30

Tags: release

References: RFC-0002:C-SELF-UPDATE, ADR-0041, RFC-0002:C-PRE-1-RELEASE-TARGET-COMPATIBILITY

Context

ADR-0041 aligned self-update and cargo-binstall with five target-specific assets built on native and cross runners. Cross-built candidates for the six targets now governed by RFC-0002:C-PRE-1-RELEASE-TARGET-COMPATIBILITY ran successfully on matching native OS and architecture runners during evaluation. The remaining design question is how to produce those binaries and preserve the pre-1.0 target aliases without retaining duplicate toolchains or obscuring canonical compiler provenance.

Decision

Replace ADR-0041’s build and distribution choice with one pinned Linux Zig build environment for the canonical targets defined by RFC-0002:C-PRE-1-RELEASE-TARGET-COMPATIBILITY. Produce each compatibility alias by repackaging its mapped canonical executable rather than compiling a legacy variant. This direction keeps canonical artifact names aligned with compilation targets while confining pre-1.0 compatibility names to the packaging boundary. Because cross-compilation alone does not establish runtime compatibility, retain native OS and architecture coverage as a risk mitigation.

Consequences

Positive: one build environment reduces runner and toolchain divergence, Linux binaries become portable musl executables, Windows ARM gains a release path, and the RFC-governed aliases preserve pre-1.0 update paths without duplicate builds. Negative: 0.x releases carry four duplicate archives and depend on a pinned Zig container plus an auditable macOS SDK source; native smoke runners remain necessary. Alias filenames describe compatibility identity rather than compiler provenance, which can confuse SBOM, attestation, and debugging consumers; the canonical archive remains the provenance source and byte equality keeps the mapping verifiable. Neutral: macOS target names remain unchanged, and the alias mechanism ends at the RFC’s 1.0 boundary.

Alternatives Considered

Build six canonical Zig targets and publish compatibility alias archives from the same binaries. (accepted)

  • Pros: Preserves old updater and cargo-binstall asset resolution without retaining duplicate toolchains., Keeps canonical artifact names truthful to their compilation targets.
  • Cons: Adds four duplicate archives to every release.

Replace legacy GNU and MSVC assets with only the new Zig target assets. (rejected)

  • Pros: Publishes the smallest possible asset set.
  • Cons: Breaks updates from binaries that still request legacy target names.
  • Rejected because: An immutable older updater cannot discover a renamed asset in the latest release, so a one-time bridge release is insufficient for users who skip versions.

Retain the existing native and cross-runner release build matrix. (rejected)

  • Pros: Preserves the current five asset targets without compatibility packaging.
  • Cons: Retains divergent toolchains, scarce macOS build usage, and no Windows ARM artifact.
  • Rejected because: The spike demonstrated that one pinned Linux build environment can produce all required binaries while native smoke jobs preserve runtime evidence.

Publish only the established GNU and MSVC asset names and map newly built updaters to those distribution identifiers. (rejected)

  • Pros: Avoids duplicate archives while preserving filenames known to older clients.
  • Cons: Makes canonical asset names misrepresent the compilation target and requires permanent updater target mapping.
  • Rejected because: Keeping truthful canonical target archives makes build provenance inspectable, while temporary duplicate packaging is bounded to pre-1.0 releases by the governing RFC.