Zig Debugging

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

# 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. GDB with Zig

Zig emits standard DWARF debug information compatible with GDB:

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

# Launch GDB
gdb ./myapp