1 Debugging

1.1 Inspecting

ANS Forth defines some "Programming Tools", words to inspect the stack, memory, compiled code and what words are defined.

‘.S ( -- )’

displays the stacks. There are two stacks: integer and floating point.

If both stacks are empty ‘.S’ display the message ‘<stacks empty>’.
If only the floating point stack is empty, ‘.S’ displays the integer stack items in one column, one item per line, both in hex and in decimal like this:
```
12345 HEX 67890 ok
.S 
     424080 [00067890] 
      12345 [00003039] ok
```
the first line shows the topmost item.
If both stacks are not empty, ‘.S’ displays both stacks, in two columns, one item per line:
```
HEX 123456.78E90 ok
DECIMAL 123456.78E90 ok
.S 
        291 [00000123]    1.234568E+95 
 1164414608 [45678E90] ok
```
Confusing example? Remember that floating point input only works when the number base is decimal. The first number looks like a floating point number but is a good hex double integer too. Number base is hex. Thus it is accepted as hex number. Second try with decimal inputs the floating point number.
If only the integer stack is empty, ‘.S’ shows two columns: The first column is just ‘<stack empty>’, the second column is the floating point stack, topmost item first:
```
D. 1250999897744 ok
.S 
<stack empty>             1.234568E+95 ok
```

‘? ( addr -- )’

Displays the integer at address addr, equivalent to ‘ .’, thus sensitive to ‘BASE’.

‘DUMP ( addr u -- )’

Displays u bytes of memory starting at address addr. You can easily cause a segmentation fault or something like that by accessing memory that doesn’t belong to the pfe-process.

‘SEE ( ``spaces name'' -- )’

decompiles the following word trying to display a reasonable indented source text. If you define your own control structures or use extended control-flow patterns, the indentation may be suboptimal.

‘WORDS ( -- )’

1.2 Single stepping

pfe includes a simple debugging and profiling facility: You can single step though a definition after saying ‘DEBUG definition’. Next time the ‘definition’ gets executed the single stepper takes control.

When this happens you see the top stack items displayed in one line. The topmost stack item is the first in line, the second and following stack items are displayed throughout the end of the line. This line is empty if the stack is empty when the word in question executes.

On the next line you see the first word to become executed inside ‘definition’.

1.2.1 Single Stepper Keys

You see a prompt ‘>’ right of the first displayed word. At this prompt you have several options. Choose one by typing one key:

‘Enter’, ‘x’, ‘k’ or ‘Arrow down’: The displayed word will be executed without single stepping. Note that the execution of the word is slowed down a little compared to execution outside the single stepper. This is because the single stepper has to keep control to detect when the word is finished.
After the actual word finished execution the resulting stack is printed on the current line. The next line shows the next next word to become executed.

Having repeated this step several times, you can see to the right of every decompiled word what changes to the stack this word caused by comparing with the stack display on the line above.
‘d’ or ‘l’ or ‘Arrow right’: Begin single step execution of the actual word. The first word to become executed inside the definiton is displayed on the next line. The word’s display is indented by two spaces for each nesting level.
You can single step through colon-definitions and the children of defining words. You can single step only loaded words, i.e. none of the kernel words.
‘s’ or ‘j’ or ‘Arrow left’: Leaves a nesting level. The rest of the definition currently executed stepwise becomes executed fast. If you leave the outmost level, the single stepper won’t get control again. Otherwise the debugger stops after the current word is finished and offers the next word in the next lower nesting level.
‘space’: The next word to be executed is decompiled. This helps you to decide if you want to single step that word.
‘q’: Quits from the debugger. The execution of the debugged word is not continued. The stacks are not cleared or changed.
‘h’: Displays a summary of the available keys.
‘r’: Profiling: Resets the instruction counter. The debugger counts how often the inner interpreter i.e. how many Forth-primitives become executed. Using this option you can anytime reset this counter to 0 to measure an arbitrary part of code.
‘c’ Profiling: Displays the instruction counter.

About This Document

This document was generated on November 5, 2024 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

Button	Name	Go to	From 1.2.3 go to
[ << ]	FastBack	Beginning of this chapter or previous chapter	1
[ < ]	Back	Previous section in reading order	1.2.2
[ Up ]	Up	Up section	1.2
[ > ]	Forward	Next section in reading order	1.2.4
[ >> ]	FastForward	Next chapter	2
[Top]	Top	Cover (top) of document
[Contents]	Contents	Table of contents
[Index]	Index	Index
[ ? ]	About	About (help)

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One
- 1.1 Subsection One-One
  - ...
- 1.2 Subsection One-Two
  - 1.2.1 Subsubsection One-Two-One
  - 1.2.2 Subsubsection One-Two-Two
  - 1.2.3 Subsubsection One-Two-Three <== Current Position
  - 1.2.4 Subsubsection One-Two-Four
- 1.3 Subsection One-Three
  - ...
- 1.4 Subsection One-Four

This document was generated on November 5, 2024 using texi2html 5.0.