Index

ANS
API
Debugger
Download
Licensing
Links
Locals
OOP In Ficl
Parse Steps
Release History
Upgrading To 4.0

Ficl includes a simple step debugger for colon definitions and DOES> words.

To debug a word, set up the stack with any parameters the word requires, then execute:

DEBUG your-word-name-here

If the word is unnamed, or all you have is an execution token, you can instead use DEBUG-XT

The debugger invokes SEE on the word which prints a crude source listing. It then stops at the first instruction of the definition. There are six (case insensitive) commands you can use from here onwards:

I (step In)

If the next instruction is a colon defintion or does> word, steps into that word's code. If the word is a primitive, simply executes the word.

O (step Over)

Executes the next instruction in its entirety.

G (Go)

Run the word to completion and exit the debugger.

L (List)

Lists the source code of the word presently being stepped.

Q (Quit)

Abort the word and exit the debugger, clearing the stacks.

X (eXecute)

Interpret the remainder of the line as Ficl words. Any change they make to the stacks will be preserved when the debugged word continues execution. Any errors will abort the debug session and reset the VM. Usage example:

X DROP 3 \ change top argument on stack to 3

Any other character will prints a list of available debugger commands.

If there is a defined word named ON-STEP when the debugger starts, that word will be executed before every step. Its intended use is to display the stacks and any other VM state you find interesting. The default ON-STEP is:

: ON-STEP  ." S: " .S-SIMPLE CR ;

If you redefine ON-STEP, we recommend you ensure the word has no side-effects (for instance, adding or removing values from any stack).

.ENV ( -- )

Prints all environment settings non-destructively.

.S ( -- )

Prints the parameter stack non-destructively in a verbose format.

.S-SIMPLE ( -- )

Prints the parameter stack non-destructively in a simple single-line format.

F.S ( -- )

Prints the float stack non-destructively (only available if FICL_WANT_FLOAT is enabled).

R.S ( -- )

Prints a represention of the state of the return stack non-destructively.

The debugger words are mostly located in source file tools.c. There are supporting words (DEBUG and ON-STEP) in softcore.fr as well. There are two main words that make the debugger go: debug-xt and step-break. debug-xt takes the execution token of a word to debug (as returned by ' for example) , checks to see if it is debuggable (not a primitive), sets a breakpoint at its first instruction, and runs see on it. To set a breakpoint, debug-xt replaces the instruction at the breakpoint with the execution token of step-break, and stores the original instruction and its address in a static breakpoint record. To clear the breakpoint, step-break simply replaces the original instruction and adjusts the target virtual machine's instruction pointer to run it.

step-break is responsible for processing debugger commands and setting breakpoints at subsequent instructions.

The debugger needs to exit automatically when it encounters the end of the word it was asked to debug. (Perhaps this could be a special kind of breakpoint?)

Add user-set breakpoints.

Add "step out" command.