ReferenceTools
Traces, the debugger and runtime errors
The normative description of each tool.
Normative text from spec/tools/trace-debug.md.
Status: draft for 0.3.0. Sources: plan/50-debugging.md, decisions 41,
43.
- Traps (checked builds) print the rule, the place and local values in source terms (positions in the file's base, ranges by name), plus the call trace. Output written so far is flushed first.
cpl trace d inputwrites one HTML file: every top-level statement and part call with its inputs and result, each read token with the value it became and the line that consumed it, and collapsible loops. Quiet by default: no per-iteration rows unless a filter asks (--at line,--var name,--when expr).- Stage snapshots:
cpl snapsaves a part's inputs;cpl run d --stage snapreruns only that part while iterating. debug(x)prints with a source location in checked builds and is removed from submissions.- The debugger (
cpl debug, DAP for editors) runs on the interpreter: breakpoints, conditional breakpoints, step into generators and closures, watch expressions in the language, and reverse step over the recorded run. - Interpreter and C++ agree on every program, including on input they
reject;
cpl selftestchecks it.