zig-compiler

Zig Compiler

目的

Zig コンパイラーの呼び出し方法をエージェントに案内します。最適化モード、出力形式、C コンパイラーの代替としての zig cc、エラーメッセージの読み方、Zig のコンパイルパイプラインを説明します。

トリガー

• 「Zig プログラムをコンパイルするにはどうすればよいですか？」
• 「Zig の最適化モードにはどのようなものがあり、それぞれいつ使えばよいですか？」
• 「C コードをコンパイルするために zig cc を使うにはどうすればよいですか？」
• 「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 での安全性チェック：

• 整数オーバーフロー → 検出され、ソース位置を示してパニックになります
• 配列境界チェック → 範囲外アクセスでパニックになります
• null ポインタのデリファレンス → クラッシュではなく、パニックになります
• unreachable → パニックになります
• enum タグの検証 → 不正なキャストでパニックになります

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	comptime でのオーバーフロー（コンパイル時に検出）
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 を使います