ref: 7d02e382d314d5bdde7978ccb7a64ea9201d03db
dir: /doc/debugger.html/
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META name='Description' content='Ficl - embedded scripting with object oriented programming'>
<META name='Keywords' content='scripting prototyping tcl OOP Forth interpreter C'>
<LINK rel='SHORTCUT ICON' href='ficl.ico'>
<TITLE>ficl debugger</TITLE>
<style>
blockquote { margin-left: 1em }
</style>
</HEAD>
<BODY>
<table border=0 cellspacing=0 width=100%%><tr>
<td width=112 bgcolor=#004968 colspan=3>
<img src=graphics/ficl.4.96.jpg height=96 width=96>
</td>
<td bgcolor=#004968>
<font face=arial,helvetica color=white size=7><b><i>
ficl debugger
</i></b></font>
</td></tr>
<tr>
<td bgcolor=#004968 width=10></td>
<td bgcolor=#004968 valign=top>
<br><p>
<a href=index.html><font face=arial,helvetica color=white><b>Index</b></font></a><p>
<p><br>
<a href=dpans.html><font face=arial,helvetica color=white><b>ANS</b></font></a><br>
<a href=api.html><font face=arial,helvetica color=white><b>API</b></font></a><br>
<a href=debugger.html><font face=arial,helvetica color=white><b>Debugger</b></font></a><br>
<a href=http://sourceforge.net/project/showfiles.php?group_id=24441><font face=arial,helvetica color=white><b>Download</b></font></a><br>
<a href=license.html><font face=arial,helvetica color=white><b>Licensing</b></font></a><br>
<a href=links.html><font face=arial,helvetica color=white><b>Links</b></font></a><br>
<a href=locals.html><font face=arial,helvetica color=white><b>Locals</b></font></a><br>
<a href=oop.html><font face=arial,helvetica color=white><b>OOP In Ficl</b></font></a><br>
<a href=parsesteps.html><font face=arial,helvetica color=white><b>Parse Steps</b></font></a><br>
<a href=releases.html><font face=arial,helvetica color=white><b>Release History</b></font></a><br>
<a href=upgrading.html><font face=arial,helvetica color=white><b>Upgrading To 4.0</b></font></a><br>
</td><td bgcolor=#004968 width=5></td><td valign=top><blockquote><p>
<p>Ficl includes a simple step debugger for colon definitions
and <code>DOES></code> words.
<p>
</blockquote><table border=0 bgcolor=#a0a0a0 width=100%><tr>
<td width=1em></td>
<td>
<font face=arial,helvetica color=#004968 size=5><b><i>
<a name='UsingTheFiclDebugger'>
Using The Ficl Debugger
</a></i></b></font></td></tr></table><p><blockquote>
To debug a word, set up the stack with any parameters the word requires,
then execute:
<pre><b>DEBUG <i>your-word-name-here</i></b></pre>
<p>
If the word is unnamed, or all you have is an execution token,
you can instead use <code>DEBUG-XT</code></b>
<p>
The debugger invokes <tt>SEE</tt> 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:
<dl>
<dt>
<b>I</b> (step <b>I</b>n)
<dd>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.
<dt>
<b>O</b> (step <b>O</b>ver)
<dd>
Executes the next instruction in its entirety.
<dt>
<b>G</b> (<b>G</b>o)
<dd>
Run the word to completion and exit the debugger.
<dt>
<b>L</b> (<b>L</b>ist)
<dd>
Lists the source code of the word presently being stepped.
<dt>
<b>Q</b> (<b>Q</b>uit)
<dd>
Abort the word and exit the debugger, clearing the stacks.
<dt>
<b>X</b> (e<b>X</b>ecute)
<dd>
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:
<pre>
X DROP 3 \ change top argument on stack to 3
</pre>
</dl>
Any other character will prints a list of available debugger commands.
<p>
</blockquote><table border=0 bgcolor=#b8b8b8 width=100%><tr>
<td width=1em></td>
<td>
<font face=arial,helvetica color=#004968 size=4><b><i>
<a name='ThecodeON-STEP/codeEvent'>
The <code>ON-STEP</code> Event
</a></i></b></font></td></tr></table><p><blockquote>
If there is a defined word named <code>ON-STEP</code> 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 <code>ON-STEP</code> is:
<p>
<pre>
: ON-STEP ." S: " .S-SIMPLE CR ;
</pre>
If you redefine <code>ON-STEP</code>, we recommend you ensure the word has no
side-effects (for instance, adding or removing values from any stack).
<p>
</blockquote><table border=0 bgcolor=#d0d0d0 width=100%><tr>
<td width=1em></td>
<td>
<font face=arial,helvetica color=#004968 size=3><b><i>
<a name='OtherUsefulWordsForDebuggingAndcodeON-STEP/code'>
Other Useful Words For Debugging And <code>ON-STEP</code>
</a></i></b></font></td></tr></table><p><blockquote>
<dl>
<dt>
<code>.ENV ( -- )</code>
<dd>
Prints all environment settings non-destructively.
<dt>
<code>.S ( -- )</code>
<dd>
Prints the parameter stack non-destructively in a verbose format.
<dt>
<code>.S-SIMPLE ( -- )</code>
<dd>
Prints the parameter stack non-destructively in a simple single-line format.
<dt>
<code>F.S ( -- )</code>
<dd>
Prints the float stack non-destructively (only available if <code>FICL_WANT_FLOAT</code> is enabled).
<dt>
<code>R.S ( -- )</code>
<dd>
Prints a represention of the state of the return stack non-destructively.
</dl>
<p>
</blockquote><table border=0 bgcolor=#a0a0a0 width=100%><tr>
<td width=1em></td>
<td>
<font face=arial,helvetica color=#004968 size=5><b><i>
<a name='DebuggerInternals'>
Debugger Internals
</a></i></b></font></td></tr></table><p><blockquote>
<p>
The debugger words are mostly located in source file <code>tools.c</code>. There are
supporting words (<code>DEBUG</code> and <code>ON-STEP</code>) in <code>softcore.fr</code> as well.
There are two main words that make the debugger go: <code>debug-xt</code> and <code>step-break</code>.
<code>debug-xt</code> takes the execution token of a word to debug (as returned by <code>'</code> for example) ,
checks to see if it is debuggable (not a primitive), sets a breakpoint at its
first instruction, and runs <code>see</code> on it. To set a breakpoint,
<code>debug-xt</code>
replaces the instruction at the breakpoint with the execution token of <code>step-break</code>, and
stores the original instruction and its address in a static breakpoint
record. To clear the breakpoint, <code>step-break</code> simply replaces the original
instruction and adjusts the target virtual machine's instruction pointer
to run it.
<p>
<code>step-break</code> is responsible for processing debugger commands and setting
breakpoints at subsequent instructions.
<p>
</blockquote><table border=0 bgcolor=#a0a0a0 width=100%><tr>
<td width=1em></td>
<td>
<font face=arial,helvetica color=#004968 size=5><b><i>
<a name='FutureEnhancements'>
Future Enhancements
</a></i></b></font></td></tr></table><p><blockquote>
<dl>
<li>
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?)
<li>Add user-set breakpoints.
<li>Add "step out" command.
</dl>
</blockquote><p></td></tr></table></body></html>