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

Mode	Flag	-O equiv	Purpose
Debug (default)	-O Debug	-O0 -g	Fast compile, all safety checks, debug info
ReleaseSafe	-O ReleaseSafe	-O2 + checks	Optimized with safety checks retained
ReleaseFast	-O ReleaseFast	-O3	Maximum speed, safety checks removed
ReleaseSmall	-O ReleaseSmall	-Os	Minimize binary size

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