ref: 58346fc70b1f39f6cedfad8a86823262b6f72290
parent: b2efd53776f2279045f42a2a95467b47f33da01c
author: jsadler <jsadler@ficl.sf.net>
date: Sun Oct 1 18:48:36 CDT 2000
*** empty log message ***
--- /dev/null
+++ b/doc/ficl_debug.html
@@ -1,0 +1,107 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="Author" content="john sadler">
+ <meta name="GENERATOR" content="Mozilla/4.73 [en] (Win98; U) [Netscape]">
+ <title>FIcl Debugger</title>
+</head>
+<body>
+<link REL="SHORTCUT ICON" href="ficl.ico">
+<h1>
+<b>Ficl Debugger</b></h1>
+
+<table BORDER=0 CELLSPACING=3 WIDTH="640" >
+<tr>
+<td><b>Forth Inspired Command Language </b></td>
+
+<td ROWSPAN="4"><img SRC="ficl_logo.jpg" height=64 width=64></td>
+
+<td ROWSPAN="4"><a href="http://www.links2go.net/topic/Forth"><img SRC="skey.gif" ALT="Key Resource" BORDER=0 height=81 width=81></a></td>
+</tr>
+
+<tr>
+<td><b>Author: John Sadler (<a href="mailto:john_sadler@alum.mit.edu">john_sadler@alum.mit.edu</a>)</b></td>
+</tr>
+
+<tr>
+<td><b>Created: 19 July 1997 </b></td>
+</tr>
+
+<tr>
+<td><b>Revision 2.05: August 2000</b></td>
+</tr>
+</table>
+
+<br>
+<table COLS=1 WIDTH="650" >
+<tr>
+<td>Ficl release 2.05 includes a simple step debugger for colon definitions
+and does> words. If you use it and can suggest improvements (or better
+yet if you write some), please let me know.
+<h2>
+Using the debugger</h2>
+To debug a word, set up the stack with any parameters the word requires,
+then type:
+<br>debug <your word here>
+<br>If the word is unnamed, or all you have is an xt, you can instead use:
+<br>debug-xt ( xt -- )
+<p>The debugger invokes <tt>see</tt> on the word, printing a crude source
+listing, then stops at the first instruction of the definition. There are
+four (case insensitive) commands you can use from here onwards:
+<dl>
+<dt>
+I (step in)</dt>
+
+<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.</dd>
+
+<dt>
+O (step over)</dt>
+
+<dd>
+Executes the next instruction in its entirety</dd>
+
+<dt>
+G (go)</dt>
+
+<dd>
+Run the word to completion and exit the debugger</dd>
+
+<dt>
+Q (quit)</dt>
+
+<dd>
+Abort the word and exit the debugger, clearing the stack</dd>
+</dl>
+
+<h2>
+The on-step event </h2>
+If there is a defined word named on-step when the debugger starts, that
+word will be executed before every step. As a guideline, this word should
+have no side effects. Its intended use is to display the stack, but you
+may have some better ideas. Please let me know.
+<br><b><tt>: on-step ." Stack: " .s cr ;</tt></b>
+<br>
+<h2>
+Debugger internals</h2>
+The debugger words are mostly located in source file tools.c. There is
+one supporting word (debug) in softcore.fr as well. There are two main
+words that make the debugger go: debug-xt and step-break. Debug-xt takes
+the xt of a word to debug (as returned by <tt>'</tt>, for example) checks
+to see if it is debuggable (not a primitive), sets a breakpoint at its
+first instruction, and runs <tt>see</tt> on it. To set a breakpoint, debug-xt
+replaces the instruction at the breakpoint with the xt 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.
+<br>Step-break is responsible for processing debugger commands and setting
+breakpoints at subsequent instructions.
+<br> </td>
+</tr>
+</table>
+
+</body>
+</html>