ForthOS Debugger

Introduction

FortOS offers a symbolic debugger, optionally with source code referencing. It is implemented by inserting debug traps in the generated code, and optionally tabulating source code locations against object code addresses.

Activating

All the debugger words are in the "extensions" vocabulary.

To enable debug traps, invoke the "[+debug]" word; as expected by the presence of the braces, this is an immediate word and debug code generation can be enabled or disabled at points within a definition. "[-debug]" disables debug code generation.

Source-to-object tabulation is kept if the "+g" word is invoked. "-g" turns it back off. Several words of storage are used for each word parsed in the input stream, so global use across large amounts of source could result in surprisingly large memory consumption.

Breakpoints

To cause the debugger to be entered when WORD is reached, simply enter "debug WORD". If you later want to delete this breakpoint, "undebug WORD" can be used. If you want to clear all breakpoints, "Undebug" (initial capital) does the trick.

If any breakpoints are active, the debugger will also be entered when an abort occurs. An easy trick to catch only aborts is to enter "debug @". Fetch, being a code word, does not have any debug trapping and thus doesn't care that its address is recorded in the debugger table. However, when an abort happens, the debugger thinks it has breakpoints active, and thus will drop you into debugger mode.

Debugger Commands

Once you're in the debugger, the following commands are available. Generally, just striking the key will result in the given action, unless specifically noted.

(space)
Pressing space causes the debugged program to step forward one word, stepping over function calls.
s
"s" causes a single step, but steps down into function calls.
c
"c" continues execution until another breakpoint (or abort).
d
"d" deletes the currently entered breakpoint.
w
"w" displays the return stack, interpreted symbolically where possible.
/
"/" starts displaying memory, starting at the address on top of the return stack. Space or "+" advance one cell, "-" backs up. "q" or RETURN end this mode and go back to the main debugger.
:
":" inputs a line of input, and then executes it via the Forth interpreter. Be careful not to use this if the code you're debugging is also using the Forth command line facilities.
‹
"‹" examines the return stack, starting at its top. If the address has source block and line number information, the source itself will be displayed, with the source corresponding to this address highlighted. Subsequent "‹" commands move further back in the stack, and "›" moves forward.
a
"a" causes the debugger to abort the word being debugged.
U
"U" causes all breakpoints to be cleared (you remain in the debugger).