Catcrafts/Crafter.Debug
Watch
2
0
Fork
You've already forked Crafter.Debug
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Crafter.Debug/tooling/AGENTS.consumer.md
Jorijn van der Graaf 8b995cd76a
 docs: the manual, notes for agents, and the notes consumers get 
- 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>
2026-11-01 02:12:17 +01:00

1.7 KiB
Raw Blame History

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 waits 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.