Environment Variables

Three variables gate behaviour you will hit immediately.

ZAZA_EXAMPLES

Restricts which examples are wired into the root build graph. The value is a comma-separated list of example names, matched case-insensitively. Whitespace around each entry is trimmed and empty entries are ignored.

If the variable is unset, every example is enabled. If it is set, only the listed names are enabled. Any value that matches nothing, including none, disables all of them; none is a convention rather than a keyword.

ZAZA_EXAMPLES=none zig build test              # no examples at all
ZAZA_EXAMPLES=mixed-stack zig build mixed-stack-run
ZAZA_EXAMPLES=wasm-wasi,wasm-exports zig build wasm-wasi-report

This matters more than it looks. Zig resolves every declared dependency while the build graph is being constructed, before any step runs. With all examples enabled, configuring the graph pulls in JUCE, curl, mbedtls, zlib, spdlog, and fmt. ZAZA_EXAMPLES=none is what CI uses for the fast job, and it is the right default for the edit-test loop.

The names are the target prefixes: json, juce, zaza-juce, rust-interop, proof-library, generated-code, package-producer, package-consumer, mixed-stack, interface-object-graph, test-workflows, generated-headers, shared-plugin, preset-profiles, cross-compile-cli, resources-bundle, bindings, benchmark-workflow, cxx20-modules, wasm-wasi, wasm-exports, cmake-combo, cmake-net, cmake-shim.

hello-zaza and run-hello-zaza are registered unconditionally and are present even under ZAZA_EXAMPLES=none.

ZAZA_SYSTEM_CMDS

Enables build steps that shell out to external tools, chiefly git and cmake. Accepts 1, true, yes, on and their negatives; the default is off. The build-time flag -Dsystem-cmds=true does the same thing and takes precedence.

ZAZA_SYSTEM_CMDS=1 zig build cmake-shim

When it is off, the build prints its state at the top of every run:

[config] system-cmds=false (deps must already exist)

and cmake-shim reports that it is skipping:

[cmake-shim] skipped: system-cmds=false. Run with -Dsystem-cmds=true or ZAZA_SYSTEM_CMDS=1 to enable.

With it on:

[config] system-cmds=true (git/cmake enabled)

The gate exists so that a routine build never silently clones repositories or invokes CMake. Three examples opt themselves in regardless, because their whole point is CMake: cmake_combo, cmake_net, and the JUCE examples. Only cmake_shim genuinely requires the variable.

Note that cmake-shim-run and cmake-install are registered only when system commands are enabled. Without the variable those step names do not exist.

ZAZA_REGISTRY

Controls whether the build is allowed to modify build.zig.zon. Default on.

When on, the build checks each enabled example's registry dependencies against build.zig.zon. If one is missing, it runs the fetch path, writes the entry with a resolved hash, prints a message, and panics so you re-run:

[zaza] added dependency 'fmt' to build.zig.zon; re-run zig build

Setting ZAZA_REGISTRY=0 skips that check entirely. Use it when you want the build to fail loudly on a missing dependency rather than edit a tracked file, or when you are working offline. It does not disable dependencies already declared in build.zig.zon.

Only five examples trigger a fetch: juce and zaza-juce need juce, cmake-combo needs fmt and spdlog, cmake-net needs curl, zlib, and mbedtls, and json needs nlohmann_json.

The rest