Zig Compiler

Zig Compiler

Purpose

Guide agents through Zig compiler invocation: optimization modes, output types, zig cc as a C compiler drop-in, error message interpretation, and the Zig compilation pipeline.

Triggers

• "How do I compile a Zig program?"
• "What are Zig's optimization modes and when do I use each?"
• "How do I use zig cc to compile C code?"
• "How do I read Zig error messages?"
• "How do I compile a Zig library?"
• "What is zig ast-check?"

Workflow

1. Basic compilation

# Compile and run a single file
zig run src/main.zig

# Compile to executable
zig build-exe src/main.zig

# Compile to static library
zig build-lib src/mylib.zig

# Compile to shared library
zig build-lib src/mylib.zig -dynamic

# Compile to object file
zig build-obj src/main.zig

# Output name
zig build-exe src/main.zig -femit-bin=myapp

2. Optimization modes

zig build-exe src/main.zig -O Debug        # dev builds
zig build-exe src/main.zig -O ReleaseSafe  # production with safety
zig build-exe src/main.zig -O ReleaseFast  # max performance
zig build-exe src/main.zig -O ReleaseSmall # embedded/WASM

Safety checks in Debug and ReleaseSafe:

• Integer overflow → detected and panics with source location
• Array bounds checking → panics on OOB
• Null pointer dereference → panic (not crash)
• unreachable → panic
• Enum tag validation → panic on bad cast

ReleaseFast: turns safety checks into undefined behaviour (same semantics as C -O3). Use only when you've validated with ReleaseSafe first.

3. Target specification

# List all supported targets
zig targets

# Cross-compile for specific target
zig build-exe src/main.zig \
    -target aarch64-linux-gnu \
    -O ReleaseFast

# Embedded (no OS)
zig build-exe src/main.zig \
    -target thumb-freestanding-eabi \
    -O ReleaseSmall

# WebAssembly
zig build-exe src/main.zig \
    -target wasm32-freestanding \
    -O ReleaseSmall \
    --export=main

# Common target triples: cpu-os-abi
# x86_64-linux-gnu, x86_64-windows-gnu, aarch64-macos-none
# thumbv7m-freestanding-eabi, wasm32-wasi, wasm32-freestanding

4. zig cc — C compiler drop-in

Zig ships a C/C++ compiler (zig cc / zig c++) backed by Clang and musl. It is hermetic — no system libc required.

# Compile C code
zig cc -O2 -Wall main.c -o myapp

# Compile C++ code
zig c++ -std=c++17 -O2 main.cpp -o myapp

# Cross-compile C for ARM (no cross toolchain needed!)
zig cc -target aarch64-linux-gnu -O2 main.c -o myapp-arm

# Statically link with musl
zig cc -target x86_64-linux-musl main.c -o myapp-static

# Use in CMake (override compiler)
CC="zig cc" CXX="zig c++" cmake -S . -B build
cmake --build build

# Use in Makefile
CC="zig cc" make

zig cc advantages over gcc/clang:

• No system toolchain required (fully hermetic)
• Built-in cross-compilation for any supported target
• Always ships with a recent clang version
• musl libc bundled for static Linux builds

5. Emit formats

# Emit LLVM IR
zig build-exe src/main.zig --emit-llvm-ir

# Emit assembly
zig build-exe src/main.zig --emit-asm
cat main.s

# Emit binary and assembly
zig build-exe src/main.zig -femit-bin=myapp -femit-asm=myapp.s

6. AST check and syntax validation

# Check syntax without compiling
zig ast-check src/main.zig

# Format code
zig fmt src/main.zig
zig fmt src/          # format entire directory

# Check formatting without modifying
zig fmt --check src/

# Tokenize (debugging zig fmt)
zig tokenize src/main.zig

7. Reading Zig error messages

Zig error messages include:

• Source file and line
• Column indicator with arrow
• Note messages for context

src/main.zig:10:5: error: expected type 'u32', found 'i32'
    x: i32 = 5,
    ^
src/main.zig:7:5: note: struct field 'x' declared here
    x: u32,
    ^

Key error patterns:

Suppress "unused" errors:

_ = unused_variable;  // explicitly discard

8. Version and environment

# Check Zig version
zig version

# Show build configuration
zig env

# Show standard library location
zig env | grep lib_dir

For optimization mode details and target triple reference, see references/zig-optimize-modes.md.

Related skills

• Use skills/zig/zig-build-system for multi-file projects with build.zig
• Use skills/zig/zig-cinterop for calling C from Zig and vice versa
• Use skills/zig/zig-cross for cross-compilation targets and sysroots
• Use skills/zig/zig-debugging for GDB/LLDB with Zig binaries

Zig Optimization Modes Reference

Mode Comparison Table

Safety Checks Detail

Runtime detectable safety checks (Debug/ReleaseSafe)

// 1. Integer overflow
const x: u8 = 200;
const y: u8 = x + 100;  // panic: integer overflow

// Safe alternatives:
const y = x +% 100;           // wrapping add
const y = @addWithOverflow(x, 100);  // returns {result, overflowed}
const y = std.math.add(u8, x, 100) catch handle_overflow();

// 2. Array bounds
var arr = [3]u32{ 1, 2, 3 };
const x = arr[5];  // panic: index out of bounds

// 3. Null pointer optional
var opt: ?*u32 = null;
const x = opt.?;  // panic: null value

// 4. Enum tag
const val: u8 = 99;
const e = @as(MyEnum, @enumFromInt(val));  // panic if 99 is not a valid tag

// 5. Unreachable
fn get(x: u8) u8 {
    return switch (x) {
        0 => 10,
        1 => 20,
        else => unreachable,  // panic if reached in Debug/ReleaseSafe
    };
}

When to use each mode

Debug:       Development, always. Fast compile + all checks.
ReleaseSafe: Staging/production where safety matters (servers, critical code).
             Same behavior as Debug on errors — panics instead of UB.
ReleaseFast: Production after thorough testing with ReleaseSafe.
             Maximum throughput. Errors become undefined behaviour.
ReleaseSmall: WASM, embedded, CLI tools where size matters.

Panic Handling

// Default panic: prints to stderr and exits
// Custom panic handler in root file:
pub fn panic(msg: []const u8, error_return_trace: ?*std.builtin.StackTrace, ret_addr: ?usize) noreturn {
    std.log.err("PANIC: {s}", .{msg});
    // log to file, notify monitoring, etc.
    std.process.exit(1);
}

Comptime Integer Overflow

Comptime overflow is always an error, regardless of mode:

comptime {
    const x: u8 = 300;  // error: integer value 300 cannot be coerced to type 'u8'
}

Target CPU Features

# List CPU features for a target
zig targets | python3 -c "import sys,json; data=json.load(sys.stdin); [print(c['name']) for c in data['cpus'] if 'x86_64' in c.get('name','')]"

# Enable specific CPU features
zig build-exe -target x86_64-linux-gnu \
    -mcpu baseline+avx2+bmi2 \
    src/main.zig

# Native CPU (all available features)
zig build-exe -mcpu native src/main.zig

# Common CPU presets
# baseline      — minimum for the architecture
# native        — detect current machine
# x86_64-v2     — SSE4.2 (most VMs)
# x86_64-v3     — AVX2 (Haswell+)
# cortex_a72    — Raspberry Pi 4

Single-File Compilation Flags

zig build-exe [flags] src/main.zig

-O <mode>                    # Debug|ReleaseSafe|ReleaseFast|ReleaseSmall
-target <triple>             # cpu-os-abi
-mcpu <cpu[+feat...]>        # CPU/feature selection
-femit-bin=<path>            # Output binary path
-femit-asm=<path>            # Emit assembly
-femit-llvm-ir=<path>        # Emit LLVM IR
-fno-emit-bin                # Skip binary, emit other artifacts only
-I <dir>                     # Add include directory
-L <dir>                     # Add library directory
-l <name>                    # Link library
--strip                      # Strip debug info
-fstack-check                # Extra stack overflow protection
-fsingle-threaded            # Disable thread-local storage
--name <name>                # Output file name (without extension)

WASM-Specific

# WASI (WebAssembly System Interface)
zig build-exe -target wasm32-wasi -O ReleaseSmall src/main.zig
wasmtime myapp.wasm

# Freestanding WASM (browser)
zig build-exe \
    -target wasm32-freestanding \
    -O ReleaseSmall \
    --export=init \
    --export=update \
    -fno-entry \
    src/main.zig

# Check WASM binary size
wasm-opt -Oz myapp.wasm -o myapp.opt.wasm
ls -lh myapp.opt.wasm