zig-debugging

Zig のデバッグ

目的

Zig プログラムのデバッグについて、GDB／LLDB のセッション、Zig のパニックとエラーリターントレースの解釈、std.debug.print によるログ出力、デバッグビルドの設定、IDE との統合をエージェントに案内します。

トリガー

• 「GDB で Zig プログラムをデバッグするにはどうすればよいですか？」
• 「Zig のパニックメッセージはどう解釈すればよいですか？」
• 「デバッグに std.debug.print を使うにはどうすればよいですか？」
• 「Zig にエラーリターントレースが表示されます。これはどういう意味ですか？」
• 「VS Code で Zig のデバッグを設定するにはどうすればよいですか？」
• 「Zig のクラッシュからスタックトレースを取得するにはどうすればよいですか？」

ワークフロー

1. デバッグ用にビルドする

# Debug build (default) — full debug info, safety checks
zig build-exe src/main.zig -O Debug

# With build system
zig build            # uses Debug by default
zig build -Doptimize=Debug

# Run directly with debug output
zig run src/main.zig

2. Zig で GDB を使う

Zig は GDB と互換性のある標準的な DWARF デバッグ情報を出力します。

# Build with debug info
zig build-exe src/main.zig -O Debug -femit-bin=myapp

# Launch GDB
gdb ./myapp

# GDB session
(gdb) break main
(gdb) run arg1 arg2
(gdb) next          # step over
(gdb) step          # step into
(gdb) continue
(gdb) print my_var
(gdb) info locals
(gdb) bt            # backtrace

Zig のパニックにブレークポイントを設定します。

(gdb) break __zig_panic_start
(gdb) break std.builtin.default_panic

3. Zig で LLDB を使う

lldb ./myapp

(lldb) b main
(lldb) r arg1 arg2
(lldb) n            # next
(lldb) s            # step into
(lldb) p my_var     # print
(lldb) frame variable
(lldb) bt           # backtrace
(lldb) c            # continue

# Break on panic
(lldb) b __zig_panic

4. Zig のパニックを解釈する

Zig のパニックには、ソースの場所と理由が含まれます。

thread 'main' panic: index out of bounds: index 5, len 3
/home/user/src/main.zig:15:14
/home/user/src/main.zig:42:9
???:?:?: (name not available)

よくあるパニックメッセージ：

パニック	原因
index out of bounds: index N, len M	スライス／配列の範囲外アクセス
integer overflow	Debug／ReleaseSafe での算術オーバーフロー
attempt to unwrap null	null に対するオプショナルアクセス .?
reached unreachable code	unreachable が実行された
casting...	無効な列挙型タグまたは共用体へのアクセス
integer cast truncated bits	範囲外の値に対する @intCast
out of memory	アロケーターの失敗

5. エラーリターントレース

Zig はエラーリターントレースを使って、エラーがどこで伝播したかを追跡します。

error: FileNotFound
/home/user/src/main.zig:30:20: 0x10a3b in openConfig (main)
    const f = try std.fs.openFileAbsolute(path, .{});
                   ^
/home/user/src/main.zig:15:25: 0x10b12 in run (main)
    const cfg = try openConfig("/etc/myapp.conf");
                    ^
/home/user/src/main.zig:8:20: 0x10c44 in main (main)
    try run();
               ^

このトレースは、エラーが伝播した正確な try の連鎖を示します。下から上へ読みます：main → run → openConfig。

リリースビルドで有効にします。

// build.zig
const exe = b.addExecutable(.{
    .name = "myapp",
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
    .error_tracing = true,  // enable even in ReleaseFast
});

6. トレース用の std.debug.print

const std = @import("std");

pub fn main() !void {
    const x: u32 = 42;
    const name = "world";

    // Basic print (always to stderr)
    std.debug.print("x = {d}, name = {s}\n", .{ x, name });

    // Print any value (useful for structs)
    const point = Point{ .x = 1, .y = 2 };
    std.debug.print("point = {any}\n", .{point});

    // Formatted output
    std.debug.print("hex: {x}, binary: {b}\n", .{ x, x });

    // Log levels (respects compile-time log level)
    const log = std.log.scoped(.my_module);
    log.debug("debug info: {d}", .{x});
    log.info("started processing", .{});
    log.warn("unusual condition", .{});
    log.err("failed: {s}", .{"reason"});
}

7. std.log の設定

// Override default log level at root
pub const std_options = std.Options{
    .log_level = .debug,  // .debug | .info | .warn | .err
};

// Custom log handler
pub fn logFn(
    comptime level: std.log.Level,
    comptime scope: @TypeOf(.enum_literal),
    comptime format: []const u8,
    args: anytype,
) void {
    const prefix = "[" ++ @tagName(level) ++ "] (" ++ @tagName(scope) ++ "): ";
    std.debug.print(prefix ++ format ++ "\n", args);
}

pub const std_options = std.Options{
    .logFn = logFn,
};

8. VS Code／IDE との統合

zig.vscode-zig 拡張機能と CodeLLDB をインストールします。

.vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug Zig",
            "program": "${workspaceFolder}/zig-out/bin/myapp",
            "args": [],
            "cwd": "${workspaceFolder}",
            "preLaunchTask": "zig build"
        }
    ]
}

.vscode/tasks.json：

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "zig build",
            "type": "shell",
            "command": "zig build",
            "group": { "kind": "build", "isDefault": true },
            "problemMatcher": ["$zig"]
        }
    ]
}

関連スキル

• ビルドモードとデバッグ情報フラグについては、skills/zig/zig-compiler を使用します
• GDB の基礎については、skills/debuggers/gdb を使用します
• LLDB の基礎については、skills/debuggers/lldb を使用します
• Zig と C が混在するコードのデバッグには、skills/zig/zig-cinterop を使用します