第5章 调试 Zig 应用程序

能够熟练地调试应用程序，是每一位程序员的必备技能。无论你是新手还是专家，在开发过程中难免会遇到 Bug。本章我们将探讨在 Zig 中定位和修复问题的策略与工具。

1. 打印调试 (Print Debugging)

这是最古老、最简单，也是最常用的调试手段。核心思想很简单：让程序把它的内部状态“告诉”你。

向标准输出 (stdout) 打印

在之前的章节中，我们已经多次使用了 stdout.print()。这是最常规的输出方式。

要使用它，首先需要获取 stdout 的 writer 对象：

const std = @import("std");

pub fn main() !void {
    // 获取 stdout 的 writer
    // 注意：在实际项目中，出于性能考虑，通常会使用缓冲 writer (Buffered Writer)
    const stdout = std.io.getStdOut().writer();

    const result = add(34, 16);
    
    // 使用 {d} 格式化说明符打印整数
    try stdout.print("Result: {d}\n", .{result});
}

fn add(x: u8, y: u8) u8 {
    return x + y;
}

向标准错误 (stderr) 打印

在调试时，我们通常更倾向于将日志打印到 stderr。

1. 分离输出：将调试日志与正常的程序输出（stdout）分开。
2. 避免缓冲：stderr 通常是无缓冲的，或者缓冲行为不同，能确保日志在程序崩溃前被打印出来。

Zig 提供了一个非常方便的快捷函数 std.debug.print()，它默认输出到 stderr。这也是 Zig 社区推荐的打印调试方式。

const std = @import("std");

pub fn main() void {
    const x = 10;
    const y = 20;
    // 注意：std.debug.print 不会返回错误，使用起来更方便
    std.debug.print("Debug: x={d}, y={d}\n", .{x, y});
}

常用格式化说明符

Zig 的格式化字符串使用 {} 作为占位符。以下是一些常用的说明符：

• {d}：十进制数 (Decimal)。
• {x}：十六进制数 (HeXadecimal)。
• {s}：字符串 (String)。
• {c}：字符 (Character)。
• {*}：指针/地址。
• {any}：通用格式。当你不知道用什么，或者想打印结构体/数组时，用它。

const user = struct { id: u32, name: []const u8 }{ .id = 1, .name = "Zig" };
std.debug.print("User: {any}\n", .{user});
// 输出: User: struct { id: u32 = 1, name: []const u8 = { 90, 105, 103 } }

2. 使用调试器 (GDB / LLDB)

当问题变得复杂（例如段错误、内存破坏、死锁）时，打印调试往往力不从心。这时你需要一个真正的交互式调试器。

由于 Zig 编译出的二进制文件兼容 C ABI 和 DWARF 调试信息，你可以直接使用业界标准的调试器：

• GDB (GNU Debugger)：Linux 系统的标配。
• LLDB (LLVM Debugger)：macOS 的默认选择，也广泛用于 Linux。

编译设置

要使用调试器，必须确保编译时包含调试信息。 Zig 的默认编译模式是 Debug 模式，这非常适合调试。

# 默认就是 Debug 模式，包含调试符号，未开启优化
zig build-exe main.zig

如果你使用了 release 模式（如 -O ReleaseSafe 或 -O ReleaseFast），某些调试信息可能会被剥离或因优化而变得难以追踪。

调试实战 (以 LLDB 为例)

假设我们要调试以下代码 debug_demo.zig：

const std = @import("std");

fn calculate(a: u8, b: u8) u8 {
    const sum = a + b;
    return sum * 2;
}

pub fn main() void {
    const result = calculate(2, 3);
    std.debug.print("Result: {d}\n", .{result});
}

步骤 1：编译

zig build-exe debug_demo.zig

步骤 2：启动 LLDB

lldb ./debug_demo

步骤 3：设置断点与运行 在 lldb 提示符下：

(lldb) b main          # 在 main 函数入口设置断点
Breakpoint 1: where = debug_demo`debug_demo.main ...

(lldb) run             # 启动程序
Process 1234 launched ...
Process 1234 stopped
* thread #1, stop reason = breakpoint 1.1
    frame #0: ... debug_demo`debug_demo.main ...
-> 10   pub fn main() void {
   11       const result = calculate(2, 3);

步骤 4：单步执行与查看变量

• n (next)：执行下一行（不进入函数）。
• s (step)：进入函数内部。
• p variable (print)：打印变量的值。
• frame variable：查看当前栈帧的所有局部变量。

(lldb) s               # 进入 calculate 函数
(lldb) frame variable
(unsigned char) a = '\x02'
(unsigned char) b = '\x03'

(lldb) n               # 执行加法
(lldb) p sum           # 查看 sum 的值
(unsigned char) $0 = '\x05'

通过这种方式，你可以逐行检查程序的执行流程和状态，找出逻辑错误的根源。

3. 检查对象类型

Zig 是静态强类型语言。有时在调试或编写泛型代码时，我们需要确切知道某个变量的类型。

编译时类型检查：@TypeOf()

Zig 提供了一个内置函数 @TypeOf()，它可以在编译时返回任何表达式的类型。

const std = @import("std");

pub fn main() void {
    const x: i32 = 42;
    const y: *const i32 = &x;

    // 打印类型名称
    std.debug.print("Type of x: {any}\n", .{@TypeOf(x)});
    std.debug.print("Type of y: {any}\n", .{@TypeOf(y)});
}

输出：

Type of x: i32
Type of y: *const i32

这个功能在阅读复杂的 Zig 代码（尤其是使用了大量 comptime 和泛型的代码）时非常有帮助。

总结

1. 简单问题用 std.debug.print：记得使用 {d}、{s}、{any} 等格式化符。
2. 复杂问题用 LLDB/GDB：学会设置断点 (b)、单步执行 (n/s) 和查看变量 (p)。
3. 编译模式：调试时请保持默认的 Debug 构建模式，不要开启优化。

掌握了这些工具，你就能更有底气地面对编程中的挑战。下一章，我们将回到语法学习，深入探讨 Zig 中两个非常重要的概念：指针与可选类型。

---

原文出处: https://pedropark99.github.io/zig-book/