Zig Debugging

mohitmishra786/low-level-dev-skills/skills/zig/zig-debugging

作者 mohitmishra786bdc58472fa9f无许可证253 个星标收录于 2026年10月9日更新于 2026年10月9日仓库3个月前更新

Zig debugging skill. Use when debugging Zig programs with GDB or LLDB, interpreting Zig runtime panics, using std.debug.print for tracing, configuring debug builds, or debugging Zig programs in VS Code. Activates on queries about debugging Zig, Zig panics, zig gdb, zig lldb, std.debug.print, Zig stack traces, or Zig error return traces.

仅含说明Software Development
AI 生成的概览

指导使用 GDB、LLDB 调试 Zig 程序，解读 panic、错误返回追踪、日志记录及 IDE 配置。

功能
该技能提供调试 Zig 程序的说明。内容涵盖构建带调试信息的程序、运行 GDB 和 LLDB 会话、解读 Zig panic 消息和错误返回追踪、使用 std.debug.print 和 std.log 进行追踪，以及配置 VS Code 与 CodeLLDB。它还附带一份 Zig 调试模式参考文件。
适用场景
适用于调试 Zig 程序、解读 Zig panic 或错误返回追踪、为 Zig 配置 GDB 或 LLDB、使用 std.debug.print 或 std.log 添加追踪，或在 VS Code 中配置 Zig 调试。
运行要求
不附带脚本，仅为说明文档。需要 Zig 工具链，可选 GDB 或 LLDB；用于 IDE 时需 zig.vscode-zig 扩展和 CodeLLDB。

Zig Debugging

Purpose

Guide agents through debugging Zig programs: GDB/LLDB sessions, interpreting Zig panics and error return traces, std.debug.print logging, debug build configuration, and IDE integration.

Triggers

  • "How do I debug a Zig program with GDB?"
  • "How do I interpret a Zig panic message?"
  • "How do I use std.debug.print for debugging?"
  • "Zig is showing an error return trace — what does it mean?"
  • "How do I set up Zig debugging in VS Code?"
  • "How do I get a stack trace from a Zig crash?"

Workflow

1. Build for debugging

bash
# Debug build (default) — full debug info, safety checkszig build-exe src/main.zig -O Debug
# With build systemzig build            # uses Debug by defaultzig build -Doptimize=Debug
# Run directly with debug outputzig run src/main.zig

2. GDB with Zig

Zig emits standard DWARF debug information compatible with GDB:

bash
# Build with debug infozig build-exe src/main.zig -O Debug -femit-bin=myapp
# Launch GDBgdb ./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

Break on Zig panics:

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

3. LLDB with Zig

bash
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. Interpreting Zig panics

Zig panics include the source location and reason:

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)

Common panic messages:

PanicCause
index out of bounds: index N, len MSlice/array OOB access
integer overflowArithmetic overflow in Debug/ReleaseSafe
attempt to unwrap nullOptional access .? on null
reached unreachable codeunreachable executed
casting...Invalid enum tag or union access
integer cast truncated bits@intCast with value out of range
out of memoryAllocator failed

5. Error return traces

Zig tracks where errors propagate with error return traces:

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();               ^

The trace shows the exact try chain where the error propagated. Read bottom-up: main → run → openConfig.

Enable in release builds:

zig
// build.zigconst 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 for tracing

zig
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 configuration

zig
// Override default log level at rootpub const std_options = std.Options{    .log_level = .debug,  // .debug | .info | .warn | .err};
// Custom log handlerpub 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 integration

Install the zig.vscode-zig extension and CodeLLDB.

.vscode/launch.json:

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:

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

Related skills

  • Use skills/zig/zig-compiler for build modes and debug info flags
  • Use skills/debuggers/gdb for GDB fundamentals
  • Use skills/debuggers/lldb for LLDB fundamentals
  • Use skills/zig/zig-cinterop when debugging mixed Zig/C code

来源与署名

来源：mohitmishra786/low-level-dev-skills位于skills/zig/zig-debugging提交bdc5847

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 mohitmishra786/low-level-dev-skills 的技能

Simd Intrinsics

mohitmishra786

指导使用 x86 SSE/AVX 与 ARM NEON 内建函数编写和诊断 SIMD 向量化。

Software Development2533个月前更新

Zig Cross

mohitmishra786

指导 Zig 交叉编译：目标三元组、CPU 特性、用 zig cc 编译 C、嵌入式与 WASM 目标。

Software Development2533个月前更新

Rustc Basics

mohitmishra786

指导 Rust 编译器配置：RUSTFLAGS、Cargo 配置文件、构建调优，以及查看 MIR 或汇编输出。

Software Development2533个月前更新

Zig Cinterop

mohitmishra786

指导 Zig 与 C 互操作：@cImport、translate-c、extern 与 packed 结构体，以及 C/Zig 混合构建。

Software Development2533个月前更新

Zig Build System

mohitmishra786

指导编写和调试 Zig 的 build.zig 文件，涵盖目标、C 源码、选项、测试与包清单。

Software Development2533个月前更新

Memory Model

mohitmishra786

指导代理理解 C++ 与 Rust 内存模型、内存顺序、原子操作、栅栏及无锁模式。

Software Development2533个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新