Introduction

zut is a hermetic, incremental, content-addressed build system written in Zig 0.16, with Rust and Zig as first-class languages. It is built from scratch — its own Starlark front-end, content-addressed store, sandboxed executor, and incremental engine — in the spirit of Bazel and Buck2.

⚠️ Status: early and experimental. zut is under active development. The design is settled (see the Architecture overview), but APIs, the Starlark dialect, and the CLI will change. It is not yet ready for production builds.

What makes zut zut

• Correct by construction. A build’s output is a pure function of its declared inputs. Undeclared inputs are made physically unavailable to actions by the sandbox, so “works on my machine” drift becomes a build error instead of a mystery.
• Fine-grained incrementality. The unit of caching is the action, not the target or the crate. Change one file and zut rebuilds exactly the actions that depended on it — nothing more.
• Content-addressed caching. Every action’s inputs and outputs are addressed by their hash (BLAKE3). An identical action never runs twice, whether the result is in your local store or a shared remote cache.
• Rust & Zig as peers. A rust_binary can depend on a zig_library and vice versa, linked through the C ABI. Neither language is a bolt-on.
• Remote-ready. The execution path is shaped like the Bazel Remote Execution API (REAPI), so remote caching (today) and remote execution (later) slot in without reworking the core.
• Extensible. Build rules like rust_binary and zig_library are definitions written in Starlark over a small set of primitives (providers + actions) — not hardcoded into the engine.

How this book is organized

• Getting started — build zut, write a BUILD file, run your first build, and import crates.io dependencies.
• User guide — the CLI, configuration (.zutrc), logging, remote caching, and the sandbox tiers.
• Writing BUILD files — the Starlark dialect, rules and providers, and the built-in Rust/Zig prelude.
• Internals — how the engine fits together, for contributors and the curious.
• Project — how to contribute and where things are headed.

The authoritative design contract is docs/ARCHITECTURE.md in the repository; this book is the practical companion to it.