Package manager

Active contributors: andrewrk, mlugg, jakub-konka

Purpose

Zig has a built-in package manager that operates entirely off build.zig.zon manifests, a content-addressed global cache, and HTTP fetching. There is no central registry — packages are referenced by URL + hash or by local path. Dependencies surface in user code as Modules constructed by b.dependency(...).

Specification

The full manifest format is documented in doc/build.zig.zon.md. A minimal example, taken from this repository's own build.zig.zon:

.{
    .name = .zig,
    .version = "0.0.0",
    .dependencies = .{
        .standalone_test_cases = .{ .path = "test/standalone" },
        .link_test_cases = .{ .path = "test/link" },
    },
    .paths = .{""},
    .fingerprint = 0xc1ce108124179e16,
}

Other accepted fields (per the spec) include:

• url — where to fetch a tarball.
• hash — sha256-... content hash of the tarball after extraction.
• lazy — fetch on demand only.
• paths — which paths are part of the package.

Compiler-side implementation

File	Purpose
src/Package.zig	The Package type and helpers consumed by Compilation.
src/Package/Manifest.zig	Parses build.zig.zon.
src/Package/Fetch.zig	Downloads, extracts, and verifies tarballs.
src/Package/hash.zig	Hash format used by hash fields.
src/Package/...	Additional helpers (cache directories, URL handling).

zig fetch (in src/main.zig) is the CLI entry point that exercises the fetch path standalone.

How it works

graph LR
  Manifest["build.zig.zon"] --> Parse["Package/Manifest.zig"]
  Parse --> Resolve["Package.zig"]
  Resolve --> Fetch["Package/Fetch.zig"]
  Fetch -->|unpack tarball| Cache["global cache"]
  Cache --> Verify["Package/hash.zig"]
  Verify --> Mod["std.Build.Module"]
  Mod --> Build["zig build"]

1. The build runner reads build.zig.zon via std.zon and src/Package/Manifest.zig.
2. For each declared dependency, Package/Fetch.zig downloads the tarball (or copies a local path), extracts it into the global cache (zig env cache_dir), and hashes the result.
3. The hash is compared to hash in the manifest. Mismatch is a build error.
4. Resolved packages are exposed in build.zig via b.dependency(name, options), returning a *std.Build.Dependency whose module and artifact accessors plug into the user's build graph.

CLI surface

• zig fetch <url-or-path> — fetches a package, prints the resolved hash, and exits. Useful for adding new dependencies.
• zig init — scaffolds a project including build.zig.zon. Templates live in lib/init/.
• zig build — runs the build runner, which transitively triggers fetches.

Cache layout

The global cache directory (per-user; see zig env) contains:

• p/<package-hash>/... — extracted package trees keyed by content hash.
• tmp/... — partial downloads.
• Per-std.Build.Cache manifest directories for the build steps that use them.

Integration points

• Build runner. lib/compiler/build_runner.zig calls into std.Build which calls into src/Package/Fetch.zig for transitive resolution.
• Compilation. src/Compilation.zig accepts Package graphs as input.
• Standard library zon. lib/std/zon.zig and lib/std/zig/ZonGen.zig parse manifests; src/Sema/LowerZon.zig lowers them into compile-time values.

Entry points for modification

• New manifest field. Update doc/build.zig.zon.md, src/Package/Manifest.zig, and the build runner.
• New fetch transport. src/Package/Fetch.zig already supports http(s)://, git+..., and local paths. Add a new scheme there.
• Cache strategy change. lib/std/Build/Cache.zig.

Key source files

File	Purpose
doc/build.zig.zon.md	Manifest spec.
build.zig.zon	This repo's own manifest (test deps only).
src/Package.zig	Compiler-side Package type.
src/Package/Manifest.zig	Manifest parser.
src/Package/Fetch.zig	Fetch and verify.
lib/std/zon.zig, lib/std/zig/ZonGen.zig	ZON parsing in the stdlib.
src/Sema/LowerZon.zig	ZON → compile-time Value.