Self-hosted vs LLVM backend

Purpose

Zig has two parallel backend stories: the LLVM backend (src/codegen/llvm.zig, ~580 KB), which feeds the bundled clang/LLVM, and the self-hosted backends in src/codegen/<arch>/, which lower AIR directly to machine code. This page summarizes the matrix at this commit.

Backend selection

-fllvm and -fno-llvm toggle the backend explicitly. The default is per-target capability. src/target.zig carries the table of which backends are available for which target, and src/codegen.zig dispatches accordingly.

Capability matrix

The directories under src/codegen/ give a snapshot of the self-hosted progress:

Architecture	Self-hosted directory	Notes (from sizes / file presence)
x86_64	src/codegen/x86_64/	The most complete: CodeGen.zig ~10.4 MB, full encoder/decoder/disassembler, ~161 KB of encodings.zon.
AArch64	src/codegen/aarch64/	Active development; CodeGen + Mir + Lower + abi present.
RISC-V 64	src/codegen/riscv64/	CodeGen.zig ~326 KB; substantial.
SPARC64	src/codegen/sparc64/	Smaller scaffold.
Wasm	src/codegen/wasm/	Mature; full Wasm output via the in-tree linker.
SPIR-V	src/codegen/spirv/	GPU IR backend; spec table generated by tools/gen_spirv_spec.zig.
ARM (32-bit)	src/codegen/arm/	Skeleton.
MIPS	src/codegen/mips/	Skeleton.
C	src/codegen/c.zig	Re-emits Zig as portable C. Used for -Donly-c bootstrap.

For every architecture not in this table, LLVM is the only path at this commit.

Why self-hosted?

The reasons visible from the source structure are:

• No LLVM dependency. Bootstrapping a zig without LLVM is the goal of the -Donly-c and self-hosted x86_64 paths.
• Faster Debug builds. LLVM is slow even on -O0; the self-hosted backends skip it entirely.
• Better incremental compilation. The self-hosted linkers and backends are built around per-decl Atoms, which makes small edits very cheap. LLVM's compile model invalidates more aggressively.

Why LLVM?

• Optimization. Any Release* build benefits from LLVM's optimizer.
• Architecture coverage. LLVM supports every architecture LLVM supports.
• C/C++ compatibility. zig cc/zig c++ are LLVM-only; the self-hosted backends don't ingest C.

How to tell which one ran

zig build-exe ... -fno-llvm -fno-lld forces the self-hosted path including the in-tree linker. -fllvm (or -fuse-llvm, depending on the option name in the current src/main.zig) forces LLVM. zig env reports the build's defaults.

Tests

zig build test-behavior runs the behavior suite against multiple backends; the matrix is defined in test/tests.zig. CI scripts under ci/ exercise both paths on x86_64-linux explicitly (ci/x86_64-linux-debug.sh is no-LLVM, ci/x86_64-linux-debug-llvm.sh is LLVM).

Key source files

File	Purpose
src/codegen.zig	Backend dispatch.
src/target.zig	Per-target capability table.
src/codegen/llvm.zig	LLVM backend.
src/codegen/<arch>/CodeGen.zig	Self-hosted backends.
src/codegen/c.zig	C backend (used by -Donly-c).
src/link/Lld.zig	LLD wrapper used with the LLVM backend.
src/link/<format>.zig	In-tree linkers used with self-hosted backends.

See Code generation backends for a deeper backend tour and Linkers for the linker side.