Configuration

Configurable surfaces visible to a contributor or downstream user.

build.zig options

The compiler's build.zig exposes the following user options (b.option(...) in build.zig):

Option	Default	Effect
-Donly-c	false	Translate the compiler through the C backend. Used for bootstrapping new platforms. Forces ofmt = .c.
-Dflat	false	Layout lib/, LICENSE, README.md flat in the install prefix (for upstream packaging).
-Dsingle-threaded	unset	Build single-threaded artifacts.
-Duse-zig-libcxx	false	Force the bundled libc++ even when system libc++ is present.
-Dno-lib	false	Skip copying lib/ into the install prefix.
-Dno-langref	follows -Dno-lib	Skip building/installing doc/langref.html.
-Dstd-docs	false	Also build the standard library autodoc into doc/std/.
-Dno-bin	false	Don't emit the compiler binary (useful for doc-only builds).
-Denable-superhtml	false	Validate langref.html output with the SuperHTML checker.
-Dtracy=<path> (when supported)	unset	Link Tracy for profiling.

zig build --help prints the live list (other options may be added by test/tests.zig).

CMake variables

CMakeLists.txt exposes:

• ZIG_VERSION — overrides the version string. Default: derived via git describe.
• CMAKE_BUILD_TYPE — Debug (default), Release, RelWithDebInfo, MinSizeRel.
• CMAKE_INSTALL_PREFIX — install location. Default: ${CMAKE_CURRENT_BINARY_DIR}/stage3.
• ZIG_CMAKE_PREFIX_PATH — search path for LLVM/clang/lld packages.
• Plus the standard find_package(LLVM ...) discovery flags.

std.Options

User programs override stdlib defaults via pub const std_options: std.Options = .{ ... }. The fields (from lib/std/std.zig):

• wasiCwd — std.fs.cwd provider for WASI.
• logFn — log sink.
• log_level, log_scope_levels — logging filters.
• enable_segfault_handler — install the segfault handler.
• page_size_min, page_size_max, queryPageSize — page-size overrides.
• fmt_max_depth — std.fmt recursion limit.
• cryptoRandomSeed, crypto_always_getrandom, crypto_fork_safety, side_channels_mitigations — crypto knobs.
• http_disable_tls, http_enable_ssl_key_log_file — HTTP/TLS knobs.
• allow_stack_tracing — opt out of stack-trace machinery.

src/main.zig is a real-world example of overriding these.

CLI flags inside the compiler

The full list lives in src/main.zig. Important categories:

• -target <triple> / -mcpu=<...> — target selection.
• -O <Debug|ReleaseSafe|ReleaseFast|ReleaseSmall> — optimization mode.
• -fllvm / -fno-llvm — backend selection.
• -fuse-lld / -fno-use-lld — link with LLD or with the in-tree linker.
• -fsingle-threaded, -fno-single-threaded.
• -femit-bin=..., -femit-asm=..., -femit-llvm-ir=..., -femit-c=... — emit specific outputs.
• --watch, --listen — live rebuild modes.
• --zig-lib-dir, --cache-dir, --global-cache-dir — path overrides.

Run zig build-exe --help for the canonical list at this commit.

Environment variables

zig env reports the resolved paths. Relevant variables include:

• ZIG_LIB_DIR — override the lib path.
• ZIG_LOCAL_CACHE_DIR, ZIG_GLOBAL_CACHE_DIR — override cache locations.
• XDG_CACHE_HOME / platform equivalents — affect default cache locations.

Discovery code lives in src/introspect.zig.