Jorijn van der Graaf
8b995cd76a
- README: how the pieces fit, adding Crafter.Debug to a project (Debug::Use, the shared-args rule, Session and Pump, the AGENTS.md checklist), the app-side API with examples, the fixed-step and Crafter.Graphics patterns, a shim module for calls without #ifdefs, and the agent side: commands, exit codes, stopping apps, attaching a debugger, version skew. - AGENTS.template.md: the configurations and partitions, commands, test conventions (including the dangling Value::Find pointer two tests hit), style, design rules, security and gotchas. - tooling/AGENTS.consumer.md: what every consumer's agents read in each session, kept short: the loop, exit codes and the gotchas, pointing at `crafter-debug guide` for the rest. The QUIC transport the README describes lands next. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
23 lines
1.7 KiB
Markdown
23 lines
1.7 KiB
Markdown
## Crafter.Debug
|
|
|
|
This app can be driven while it runs: call its commands, read and set its state, pause and step it, wait for conditions, read its log, take screenshots.
|
|
|
|
- Start its debug build in the background, since it does not exit: `crafter-build <debug flag> -r`. This project's notes above name the flag, usually `--debug-api`.
|
|
- Drive it with `./build/crafter-debug` from the project directory:
|
|
- `ls --wait 60s` until it is listed; `status`, `cmds`, `help <command>`, `get '*'`
|
|
- `call <command> key=value ...`, `set <path> <value>`
|
|
- `pause --when '<condition>'` then `wait --paused`; `step 3`, `resume`
|
|
- `wait '<condition>'`, `wait --frames 30`, `wait --event <Name>`
|
|
- `trace <path> --frames 120`, `log --level warn`, `log --follow` (under Monitor)
|
|
- `screenshot`: open the PNG it prints with Read
|
|
- `quit` when done
|
|
- `./build/crafter-debug guide` is the full reference. Errors name the next step.
|
|
- Exit codes: 2 usage, 3 no instance, 4 app and client from different versions, 5 timed out, 6 the app answered an error.
|
|
|
|
Gotchas:
|
|
- Requests run when the app calls `Debug::Pump()`, once per frame. `status` shows when it last did.
|
|
- `pause` and `step` only hold what the app gates on `Debug::Advance()` or `Debug::Paused()`.
|
|
- Stopping the background `-r` task can leave the app running. Stop it with `./build/crafter-debug quit`, or `quit --force` if its loop is stuck.
|
|
- Run long `wait`s in the background, and chain short steps with `&&`.
|
|
- For breakpoints and memory, `./build/crafter-debug debugger` prints how to attach lldb or gdb inside the app's sandbox.
|
|
- To give the agent more to work with, register commands and watches in the app's debug-only code (`Debug::Command`, `Debug::Watch`, `Debug::Group`). Crafter.Debug's README shows how.
|