xx
.md
ChatGPT Claude

Zig Package

The Zig package provisions an exact official Zig host distribution. A global Zig installation is not needed.

Load an exact stable release:

load("@[email protected]", "zig", "zig_cc")

Versions must use canonical stable x.y.z form. The exact version and host artifact must exist in Zig's official index; aliases, prereleases, ranges, and version or architecture fallback are unsupported.

zig

zig is a dependency that provisions the selected distribution and puts its executable directory first in PATH. Use it with run for direct Zig commands:

load("@[email protected]", "zig")
load("@os@1", "run")

run(("zig", "build"), deps=[zig])

zig_cc

zig_cc()
zig_cc("target")

zig_cc() sets CC to the managed zig cc command and CXX to the managed zig c++ command. It also puts the managed executable directory first in PATH. With no argument, it omits -target and uses Zig's host default. Pass either no argument or one non-empty target string; None is invalid. A target is forwarded as one command field:

zig_cc("x86_64-linux-gnu")

This sets CC to managed zig cc -target x86_64-linux-gnu and CXX to managed zig c++ -target x86_64-linux-gnu. The target must be valid for Zig. Empty targets, control characters, and target fields containing both single and double quotes are rejected because Go cannot consume those compiler command fields losslessly.

Dependencies apply in declared order, so later dependencies may override PATH, CC, or CXX.

Distribution Download and Cache

Supported hosts:

The requested stable version must have an exact artifact for the host. Unsupported hosts and missing artifacts fail without version or architecture fallback.

Zig's official index is authoritative for artifact filename, size, and SHA-256. xx installs validated distributions in the operating-system user cache under xx/zig/<host-artifact>/<version> (for example, xx/zig/aarch64-macos/0.14.1). Host-artifact isolation prevents caches copied or shared across host architectures from reusing the wrong compiler. Mirror-list cache files remain directly under xx/zig. A valid same-host cached distribution needs no network request. Interactive first-time installation shows download and installation progress.

xx reads the community mirror list from https://ziglang.org/download/community-mirrors.txt. The bounded, validated list is cached with a seven-day stale-while-revalidate policy: a fresh list causes no request; a stale list is served immediately while one command-scoped background refresh runs; a missing or invalid cache refreshes synchronously. Refresh failures preserve a stale cache. Archive sources are randomized community mirrors followed by the official download.

Every source must provide both the archive and its .minisig. xx verifies the signature with the pinned Zig Software Foundation key, requires the authenticated trusted file field to equal the exact archive filename, and checks exact size and SHA-256 from the official index. Every redirect hop must remain HTTPS, and the final archive and signature URLs for a candidate must share the same normalized origin. Extraction is bounded and hardened, and the installed executable must report the requested version. Community mirror operators are untrusted; these checks make mirror use safe.

xx is not fully hermetic. First installation and mirror-list refresh depend on network availability and current official metadata; operating-system cache contents are persistent external input.

Examples

See Zig examples for direct Zig commands and Go CGO builds using Zig compilers.