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 週前更新