Five-Minute Quickstart

1. Run the test suite

ZAZA_EXAMPLES=none zig build test --summary all

Build Summary: 43/43 steps succeeded; 87/87 tests passed

ZAZA_EXAMPLES=none keeps the C++ examples out of the graph. Zig resolves every declared dependency while the graph is constructed, so leaving them on would fetch JUCE, curl, mbedtls, zlib, spdlog, and fmt just to run Zig tests.

2. Run the smallest example

ZAZA_EXAMPLES=hello-zaza zig build run-hello-zaza

=== RUN: hello_zaza_cpp ===
lang: cpp
msg: hello from zig build system

=== RUN: hello_zaza_zig ===
lang: zig
msg: hello_zaza (zig)

One Zig executable and one C++ executable, both in the same graph, both run by one step.

3. See what else exists

zig build --list-steps

With ZAZA_EXAMPLES=none that is a short list:

  install                      Copy build artifacts to prefix path
  uninstall                    Remove build artifacts from prefix path
  hello-zaza                   Build hello_zaza (Zig + C++ via Zaza)
  run-hello-zaza               Run both hello_zaza executables
  test                         Run all tests
  example-matrix               Run the verified example matrix sequentially
  all (default)                Run all tests, build default artifacts, and optionally run CMake shim
  run-cpp                      Compile and run a single C++ file (usage: zig build run-cpp -- path/to/file.cpp)
  run-zig                      Compile and run a single Zig file (usage: zig build run-zig -- path/to/file.zig)
  zaza-fetch                   Fetch a dependency into build.zig.zon (usage: zig build zaza-fetch -- <name>)

Without it, every example registers its own targets, for 61 steps in total.

4. Cross-compile something

ZAZA_EXAMPLES=cross-compile-cli zig build cross-compile-cli-report

examples/cross_compile_cli/zig-out/bin/cross_compile_cli: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, with debug_info, not stripped

A statically linked Linux binary, produced on macOS, with no cross-toolchain installed.

5. Build and consume a package

ZAZA_EXAMPLES=package-consumer zig build package-consumer-run

package consumer result: 42

That one command installs the producer library, writes its manifest, then runs a separate build file that reads the manifest and links against the result.

6. Compile and run a single file

zig build run-cpp -- src/simple_example.cpp

=== RUN: cpp ===
src: src/simple_example.cpp\nout: zig-out/bin/run_cpp\nflags: (none)
Hello from Zaza C++ example!
This is a simple test to verify Zig 0.14.0 works with C++
Build system is working!

Extra compiler flags go after the source path:

zig build run-cpp -- src/simple_example.cpp -O2

There is a Zig equivalent:

zig build run-zig -- examples/cross_compile_cli/src/main.zig

cross target: aarch64-macos