Getting started

This page covers building the compiler from this repository. For using zig as an end user, the language reference (doc/langref.html.in) and the canonical website at https://ziglang.org/learn/ are the right entry points; this page is for contributors and people who want to bootstrap their own zig.

Two-stage bootstrap

Zig builds itself in stages:

1. stage1 — a minimal zig produced by CMake from bootstrap.c, the bundled stage1/ artifacts, and Clang/LLVM. Look at bootstrap.c and CMakeLists.txt to follow the chain.
2. stage2 (self-hosted) — produced by stage1 running build.zig over src/. This is the "real" compiler in the source tree.
3. stage3 — stage2 rebuilding itself, used to verify reproducibility. The CI scripts under ci/ run this comparison on multiple architectures.

You only need a stage1 once; subsequent rebuilds use zig build directly.

Prerequisites

• A C/C++ toolchain (Clang, GCC, or MSVC).
• LLVM, LLD, and Clang development libraries matching the version pinned in CMakeLists.txt (see the find_package(LLVM ...) lines for the exact version).
• CMake ≥ 3.15 (cmake_minimum_required(VERSION 3.15)).
• A POSIX shell or PowerShell for the CI scripts.
• Optional: an existing zig binary (e.g., a nightly from https://ziglang.org/download/) lets you skip the CMake stage entirely.

Build using an existing zig

If you already have a recent zig on $PATH, the loop is:

zig build               # build the compiler
zig build test          # run the full test matrix (long)
zig build install       # install into zig-out/

build.zig exposes many useful options. From the file:

• -Dskip-install-lib-files — do not copy lib/ to the install prefix; useful while iterating.
• -Dno-bin — skip emitting the compiler binary, e.g. when you only want documentation.
• -Dstd-docs — also build the standard library autodoc.
• -Dflat — produce a layout suited to upstream packaging.
• -Donly-c — translate the compiler to portable C with the C backend (used for bootstrapping new platforms).
• -Denable-superhtml — additionally validate generated langref.html.
• -Dsingle-threaded, -Duse-zig-libcxx — variant build modes.

Build from source with CMake (cold bootstrap)

The CMake build is what CI uses to produce a stage1 from a clean machine:

mkdir build && cd build
cmake ..
make -j$(nproc) install
# Produces ./stage3/bin/zig

Inspect CMakeLists.txt for the exact set of LLVM components linked. The stage1/ directory contains zig1.wasm and helpers used by the bootstrap path.

CI reference scripts

Every supported target has its own script under ci/ (see .forgejo/workflows/ci.yaml):

• aarch64-linux-debug.sh, aarch64-linux-release.sh
• aarch64-macos-debug.sh, aarch64-macos-release.sh
• loongarch64-linux-{debug,release}.sh
• riscv64-linux-{debug,release}.sh
• s390x-linux-{debug,release}.sh
• x86_64-freebsd-{debug,release}.sh
• x86_64-linux-debug.sh, x86_64-linux-debug-llvm.sh, x86_64-linux-release.sh
• x86_64-windows-{debug,release}.ps1, aarch64-windows.ps1

Reading one of those scripts is the quickest way to see the exact commands CI runs for a given target — including the LLVM version, build flags, and which test subsets are gated per architecture.

Running tests

The full matrix is zig build test. Targeted slices are exposed as build steps in build.zig:

Step	What it runs
zig build test-behavior	test/behavior.zig and the cross-product of backends.
zig build test-cases	The compiler-error and codegen-case suite under test/cases/.
zig build test-standalone	test/standalone/* projects, each a self-contained build.zig.
zig build test-link	Linker tests in test/link/.
zig build test-cli	CLI smoke tests in test/cli/.
zig build test-c-abi	test/c_abi/.
zig build test-fmt	Run zig fmt --check over lib/, src/, test/.
zig build test-translate-c	C → Zig translation tests.
zig build test-stack-traces	Stack trace formatting tests.

zig build test --help prints the full menu generated from build.zig.

See Testing for details.

Editing day-to-day

• zig fmt formats all .zig files; zig build test-fmt enforces it.
• zig ast-check <file> reports parse errors without emitting code.
• zig std opens the standard library autodoc in a browser (uses lib/compiler/std-docs.zig).
• zig env prints the resolved lib path, cache directory, version, and target.