Debug command/event contract v1¶
Implemented by the FORTRAN AST and BASIC interpreter line monitors. This file is kept identical in the two repositories; change it together with both tests.
Start with --debug-script COMMANDS --debug-output NEWFILE. Both paths are
required. Commands come from a dedicated text file (or explicitly supplied FIFO);
the output file must not exist. Command read and log write/close failures
end the process with status 2 instead of silently resuming. Program stdin, stdout and display remain theirs.
The first stop is before the first executable statement. A script EOF disables
the monitor and resumes execution, including pending breakpoints.
Command |
Effect |
|---|---|
|
Lists supported commands and explicit exclusions |
|
Executes the stopped statement, then pauses at the next dispatch, entering source-level calls |
|
Runs until a breakpoint or program termination |
|
Adds a breakpoint; maximum 16 |
|
Removes all breakpoints |
|
Adds a variable or constant-index array element and prints it; maximum 16 |
|
Removes that watch, ignoring letter case |
|
Prints one value without registering a watch |
|
Emits a named, bounded inspection export to the log |
|
Same inspection export as |
Names use letters, digits, underscores, full stops or hyphens, maximum 64
characters. Commands are lowercase, one per line, maximum 254 characters before
the newline. Blank lines and lines beginning with # are ignored. References
have no embedded spaces; names are case-insensitive. Array subscripts are decimal
integer literals, e.g. A(2,3) or BASIC A%(2,3). Duplicate watch spellings are
idempotent; BASIC A and A! remain distinct watch registrations because the
former follows the current DEF type. Unsupported expressions and commands emit
error ... and leave execution/state unchanged. No expressions or functions are
evaluated, and absent BASIC variables/arrays are never allocated by inspection.
FORTRAN LOCATION is the physical source line in the input deck, not a statement
label. BASIC LOCATION is LINE or LINE:OFFSET, where OFFSET is the zero-based
byte offset in the tokenised line, as printed by a stop event. It is not a source
character column. A BASIC line breakpoint stops at each dispatched statement on
that line, including an inline THEN/ELSE statement. FORTRAN continuation cards do
not create extra steps. Statement functions and SAP instructions have no internal
step points in this version. A source-level CALL steps into a FORTRAN unit or a
BASIC GOSUB; a SAP call completes before the next AST stop.
The text event stream begins debug-v1 engine=... frontend=line. Stable record
prefixes are stop, value, break, checkpoint, error, resume and
capabilities; the remaining payload is native to the engine. Stop IDs increase
within a process. A checkpoint has begin scope=... and matching end records
and refers to the current stop ID. Its scope is registered watches plus FORTRAN
flags/media positions or BASIC table/stack counts/open files and bounded buffers.
It is not a full memory image, a hash of all guest state, a resumable execution
checkpoint or a record of external input. Duplicate names are allowed; use the
stop ID to distinguish them. Watch errors remain visible in the export.
next, finish, reverse stepping and restore are unsupported. BASIC AOT and
FORTRAN SAP instruction debugging are unsupported. Capabilities describe the
engine/frontend separately from the guest’s SCREEN mode. The first frontend is
a scripted text monitor, not an interactive pane or graphical inspector.
External clocks/devices keep running during a pause; wall-clock-sensitive input,
audio and TIMER/KEY events can therefore differ from an unpaused run. Watches
never call time/RNG functions, consume input or seek guest files.