zig-compiler

Zig 编译器

用途

指导 Agent 使用 Zig 编译器：优化模式、输出类型、将 zig cc 用作 C 编译器替代品、错误消息解读，以及 Zig 编译流程。

触发条件

• “如何编译 Zig 程序？”
• “Zig 有哪些优化模式？分别适用于什么情况？”
• “如何使用 zig cc 编译 C 代码？”
• “如何阅读 Zig 错误消息？”
• “如何编译 Zig 库？”
• “什么是 zig ast-check？”

工作流

1. 基本编译

# 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. 优化模式

模式	标志	-O 等效选项	用途
Debug（默认）	-O Debug	-O0 -g	快速编译，启用所有安全检查和调试信息
ReleaseSafe	-O ReleaseSafe	-O2 + checks	优化，同时保留安全检查
ReleaseFast	-O ReleaseFast	-O3	速度最快，移除安全检查
ReleaseSmall	-O ReleaseSmall	-Os	尽量减小二进制文件大小

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

Debug 和 ReleaseSafe 中的安全检查：

• 整数溢出 → 检测到后会 panic，并显示源代码位置
• 数组边界检查 → 越界时会 panic
• 空指针解引用 → 会 panic（不会崩溃）
• unreachable → 会 panic
• 枚举标签验证 → 类型转换错误时会 panic

ReleaseFast：安全检查会变为 undefined behaviour（语义与 C -O3 相同）。只有先使用 ReleaseSafe 验证后，才能使用此模式。

3. 目标规格

# 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 编译器替代品

Zig 附带一个基于 Clang 和 musl 的 C/C++ 编译器（zig cc / zig c++）。它是自包含的，无需系统 libc。

# 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

与 gcc/clang 相比，zig cc 的优势：

• 无需系统工具链（完全自包含）
• 内置支持针对任何受支持目标进行交叉编译
• 始终附带较新版本的 clang
• 为静态 Linux 构建捆绑了 musl libc

5. 输出格式

# 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 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. 阅读 Zig 错误消息

Zig 错误消息包含：

• 源文件和行号
• 带箭头的列指示符
• 提供上下文的注释消息

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,
    ^

常见错误模式：

错误	含义
error: expected type 'X', found 'Y'	类型不匹配
error: use of undeclared identifier 'X'	缺少导入或存在拼写错误
error: integer overflow	编译期溢出（编译时捕获）
error: cannot assign to constant	修改 const 变量
error: unused variable 'x'	所有变量都必须使用
error: unused function parameter 'x'	使用 _ = x; 忽略此错误

忽略“未使用”错误：

_ = unused_variable;  // explicitly discard

8. 版本与环境

# Check Zig version
zig version

# Show build configuration
zig env

# Show standard library location
zig env | grep lib_dir

有关优化模式的详细信息和目标三元组参考，请参阅 references/zig-optimize-modes.md。

相关技能

• 多文件项目（含 build.zig）请使用 skills/zig/zig-build-system
• 从 Zig 调用 C 代码及反向调用请使用 skills/zig/zig-cinterop
• 交叉编译目标和 sysroot 请使用 skills/zig/zig-cross
• 使用 Zig 二进制文件进行 GDB/LLDB 调试请使用 skills/zig/zig-debugging