diff options
Diffstat (limited to 'doc/debugger.html')
| -rw-r--r-- | doc/debugger.html | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/doc/debugger.html b/doc/debugger.html new file mode 100644 index 000000000000..31e948dd7686 --- /dev/null +++ b/doc/debugger.html @@ -0,0 +1,259 @@ +<!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> + + |