Skip to content

wado-lang/wado / .claude/skills/debugger

debugger

Verified

Use rust-gdb to inspect variables and step through code without modifying it. Prefer it over print debugging for any investigation into what the compiler is actually doing (lldb is unavailable on Claude Code Web).

FileKindSize
SKILL.mdskill md3.5 KB
---
name: debugger
description: Use rust-gdb to inspect variables and step through code without modifying it. Prefer it over print debugging for any investigation into what the compiler is actually doing (lldb is unavailable on Claude Code Web).
---

# Debugger

Debug wado compiler with rust-gdb.

## Build first

`dev` sets `debug = "line-tables-only"` and raises the workspace crates to
`opt-level = 1`, so `info locals` / `info args` come back empty in every
compiler frame. Build the `debugger` profile instead — full DWARF, no
optimization on the crates being stepped through, its own `target/debugger/`
dir so the `dev` cache stays warm:

```sh
cargo build --profile debugger --bin wado
```

## Usage

```sh
cat > scratchpad/gdb_commands.txt << 'EOF'
file ./target/debugger/wado
set pagination off
break emit_function
run compile -o scratchpad/out.wasm example/hello.wado
info locals
print func.name
bt 5
quit
EOF
rust-gdb --batch -x scratchpad/gdb_commands.txt
```

Break on a function name, not a `file:line`: a line number drifts with the
next edit above it. gdb matches a bare name in every module, so qualify one
that more than one module defines.

## Ask one question per run, not one per build

A breakpoint that fires thousands of times and gets `grep`ed answers one
question and costs a rebuild for the next. Make the breakpoint itself select:

```
break wado_compiler::wir_build::calls::local_get if $_streq(name->data_ptr, "…")
break substitute_types_in_expr
commands
silent
bt 6
continue
end
```

`bt` at a conditional hit gives the origin outright — the thing print
debugging cannot produce without guessing where to put the next `eprintln!`.

## Printing Rust values

`printf "%s", s` fails on a Rust `String` (it is a struct, not a `char*`) and
aborts the whole command file with `Value can't be converted to integer`. Use
`print`, which rust-gdb's pretty printers handle:

```
print fq              # "core:prelude/string.wado/String^Eq::eq"
print *expr
print info.struct_name
```

`$_streq(s->data_ptr, "lit")` is the way to compare one inside a breakpoint
condition.

## Batch runs

`rust-gdb --batch` exits on the first command error, so a typo in a `commands`
block silently truncates the rest of the run — check the tail of the output for
`Error in sourced command file` before trusting an empty result. Redirect to a
file and grep it; the DWO-loading noise otherwise buries the hits:

```sh
rust-gdb --batch -x scratchpad/gdb_commands.txt > scratchpad/gdb.log 2>&1
grep -a '^\$[0-9]* = ' scratchpad/gdb.log | sort -u
```

## When a guard beats a breakpoint

The debugger answers "what is this value here". When the question is "where
else does this invariant break", an assertion at the point the invariant must
hold enumerates every violation in one run and keeps doing so afterwards —
the same reason a newtype that makes an illegal name unconstructible beats
chasing one miscompile at a time. Reach for `debug_assert!` / `assert!` in the
merge or registration step first, and for gdb once it fires and you need the
values behind it.

## Common commands

| Command       | Description                   |
| ------------- | ----------------------------- |
| `info locals` | Show local variables          |
| `info args`   | Show function arguments       |
| `print *expr` | Dereference and print pointer |
| `bt 5`        | Backtrace (top 5 frames)      |
| `continue`    | Resume execution              |

## Notes

lldb does not work in Claude Code Web due to ptrace restrictions:

```
error: Cannot launch '...': personality get failed: Invalid argument
```

Use rust-gdb instead.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall