zig-compiler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zig Compiler

Zig 编译器

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.

指导开发者完成Zig编译器的调用：包括优化模式、输出类型、将

zig cc

作为C编译器替代方案、错误消息解读以及Zig编译流程。

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?"

"如何编译Zig程序？"
"Zig的优化模式有哪些，分别何时使用？"
"如何使用zig cc编译C代码？"
"如何解读Zig错误消息？"
"如何编译Zig库？"
"zig ast-check是什么？"

Workflow

操作流程

1. Basic compilation

1. 基础编译

bash

undefined

bash

undefined

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

undefined

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

undefined

2. Optimization modes

2. 优化模式

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

bash

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.

模式	参数	`-O` 等效参数	用途
`Debug` （默认）	`-O Debug`	`-O0 -g`	编译速度快，保留所有安全检查，包含调试信息
`ReleaseSafe`	`-O ReleaseSafe`	`-O2 + 检查`	已优化且保留安全检查
`ReleaseFast`	`-O ReleaseFast`	`-O3`	最大速度，移除安全检查
`ReleaseSmall`	`-O ReleaseSmall`	`-Os`	最小化二进制文件大小

bash

zig build-exe src/main.zig -O Debug        # 开发构建
zig build-exe src/main.zig -O ReleaseSafe  # 带安全保障的生产构建
zig build-exe src/main.zig -O ReleaseFast  # 最高性能构建
zig build-exe src/main.zig -O ReleaseSmall # 嵌入式/WASM构建

Debug

和

ReleaseSafe

中的安全检查：

整数溢出 → 被检测到并在源码位置触发panic
数组越界检查 → 越界时触发panic
空指针解引用 → 触发panic（而非崩溃）
```
unreachable
```
→ 触发panic
枚举标签验证 → 类型转换错误时触发panic

ReleaseFast

：将安全检查转换为

未定义行为

（与C语言

-O3

语义相同）。仅当已通过

ReleaseSafe

验证后再使用。

3. Target specification

3. 目标平台指定

bash

undefined

bash

undefined

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

常见目标平台三元组：cpu-os-abi

x86_64-linux-gnu, x86_64-windows-gnu, aarch64-macos-none

thumbv7m-freestanding-eabi, wasm32-wasi, wasm32-freestanding

undefined

undefined

4. zig cc — C compiler drop-in

4. zig cc — C编译器替代方案

Zig ships a C/C++ compiler (

zig cc

zig c++

) backed by Clang and musl. It is hermetic — no system libc required.

bash

undefined

Zig附带了基于Clang和musl的C/C++编译器（

zig cc

zig c++

）。它是自包含的——无需系统libc。

bash

undefined

Compile C code

编译C代码

zig cc -O2 -Wall main.c -o myapp

Compile C++ code

编译C++代码

zig c++ -std=c++17 -O2 main.cpp -o myapp

Cross-compile C for ARM (no cross toolchain needed!)

交叉编译C代码到ARM架构（无需交叉工具链！）

zig cc -target aarch64-linux-gnu -O2 main.c -o myapp-arm

Statically link with musl

使用musl静态链接

zig cc -target x86_64-linux-musl main.c -o myapp-static

Use in CMake (override compiler)

在CMake中使用（覆盖编译器）

CC="zig cc" CXX="zig c++" cmake -S . -B build cmake --build build

Use in Makefile

在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

CC="zig cc" make


`zig cc`相比gcc/clang的优势：
- 无需系统工具链（完全自包含）
- 内置对所有支持目标平台的交叉编译
- 始终附带最新版本的clang
- 捆绑musl libc用于Linux静态构建

5. Emit formats

5. 输出格式

bash

undefined

bash

undefined

Emit LLVM IR

输出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

undefined

zig build-exe src/main.zig -femit-bin=myapp -femit-asm=myapp.s

undefined

6. AST check and syntax validation

6. AST检查与语法验证

bash

undefined

bash

undefined

Check syntax without compiling

检查语法而不编译

zig ast-check src/main.zig

Format code

格式化代码

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

zig fmt src/main.zig zig fmt src/ # 格式化整个目录

Check formatting without modifying

检查格式而不修改文件

zig fmt --check src/

Tokenize (debugging zig fmt)

分词（调试zig fmt）

zig tokenize src/main.zig

undefined

zig tokenize src/main.zig

undefined

7. Reading Zig error messages

7. 解读Zig错误消息

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:

Error	Meaning
`error: expected type 'X', found 'Y'`	Type mismatch
`error: use of undeclared identifier 'X'`	Missing import or typo
`error: integer overflow`	Comptime overflow (caught at compile)
`error: cannot assign to constant`	Mutating a `const` variable
`error: unused variable 'x'`	All variables must be used
`error: unused function parameter 'x'`	Use `_ = x;` to suppress

Suppress "unused" errors:

zig

_ = unused_variable;  // explicitly discard

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;` 来抑制错误

抑制“未使用”错误：

zig

_ = unused_variable;  // 显式丢弃

8. Version and environment

8. 版本与环境

bash

undefined

bash

undefined

Check Zig version

检查Zig版本

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](references/zig-optimize-modes.md).

zig env | grep lib_dir


有关优化模式详情和目标平台三元组参考，请查看[references/zig-optimize-modes.md](references/zig-optimize-modes.md)。