zig-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 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:

```bash
# 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
```

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:
| Panic | Cause |
|-------|-------|
| `index out of bounds: index N, len M` | Slice/array OOB access |
| `integer overflow` | Arithmetic overflow in Debug/ReleaseSafe |
| `attempt to unwrap null` | Optional access `.?` on null |
| `reached unreachable code` | `unreachable` executed |
| `casting...` | Invalid enum tag or union access |
| `integer cast truncated bits` | `@intCast` with value out of range |
| `out of memory` | Allocator 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:

From Yabuku-xD/omfx, MIT.

More from Yabuku-xD/omfx