[gforth] / gforth / doc / gforth.ds  

gforth: gforth/doc/gforth.ds

Diff for /gforth/doc/gforth.ds between version 1.76 and 1.77

version 1.76, Fri Aug 18 08:56:32 2000 UTC version 1.77, Mon Aug 21 20:08:02 2000 UTC
Line 170 
Line 170 
 * Name Index::                  Forth words, only names listed  * Name Index::                  Forth words, only names listed
 * Concept Index::               A menu covering many topics  * Concept Index::               A menu covering many topics
   
 @detailmenu --- The Detailed Node Listing ---  @detailmenu
    --- The Detailed Node Listing ---
   
 Gforth Environment  Gforth Environment
   
Line 358 
Line 359 
   
 Programming Tools  Programming Tools
   
   * Examining::
   * Forgetting words::
 * Debugging::                   Simple and quick.  * Debugging::                   Simple and quick.
 * Assertions::                  Making your programs self-checking.  * Assertions::                  Making your programs self-checking.
 * Singlestep Debugger::         Executing your program word by word.  * Singlestep Debugger::         Executing your program word by word.
Line 8719 
Line 8722 
 @cindex programming tools  @cindex programming tools
   
 @menu  @menu
   * Examining::
   * Forgetting words::
 * Debugging::                   Simple and quick.  * Debugging::                   Simple and quick.
 * Assertions::                  Making your programs self-checking.  * Assertions::                  Making your programs self-checking.
 * Singlestep Debugger::         Executing your program word by word.  * Singlestep Debugger::         Executing your program word by word.
 @end menu  @end menu
   
 @node Debugging, Assertions, Programming Tools, Programming Tools  @node Examining, Forgetting words, Programming Tools, Programming Tools
 @subsection Debugging  @subsection Examining data and code
 @cindex debugging  @cindex examining data and code
   @cindex data examination
 Languages with a slow edit/compile/link/test development loop tend to  @cindex code examination
 require sophisticated tracing/stepping debuggers to facilate debugging.  
   
 A much better (faster) way in fast-compiling languages is to add  
 printing code at well-selected places, let the program run, look at  
 the output, see where things went wrong, add more printing code, etc.,  
 until the bug is found.  
   
 The simple debugging aids provided in @file{debugs.fs}  
 are meant to support this style of debugging. In addition, there are  
 words for non-destructively inspecting the stack and memory:  
   
   The following words inspect the stack non-destructively:
   
 doc-.s  doc-.s
 doc-f.s  doc-f.s
   
   There is a word @code{.r} but it does @i{not} display the return stack!
 There is a word @code{.r} but it does @i{not} display the return  It is used for formatted numeric output (@pxref{Simple numeric output}).
 stack! It is used for formatted numeric output.  
   
   
 doc-depth  doc-depth
 doc-fdepth  doc-fdepth
 doc-clearstack  doc-clearstack
   
   The following words inspect memory.
   
 doc-?  doc-?
 doc-dump  doc-dump
   
   And finally, @code{see} allows to inspect code:
   
 The word @code{~~} prints debugging information (by default the source  doc-see
 location and the stack contents). It is easy to insert. If you use Emacs  doc-xt-see
 it is also easy to remove (@kbd{C-x ~} in the Emacs Forth mode to  
 query-replace them with nothing). The deferred words  
 @code{printdebugdata} and @code{printdebugline} control the output of  
 @code{~~}. The default source location output format works well with  
 Emacs' compilation mode, so you can step through the program at the  
 source level using @kbd{C-x `} (the advantage over a stepping debugger  
 is that you can step in any direction and you know where the crash has  
 happened or where the strange data has occurred).  
   
 The default actions of @code{~~} clobber the contents of the pictured  @node Forgetting words, Debugging, Examining, Programming Tools
 numeric output string, so you should not use @code{~~}, e.g., between  @subsection Forgetting words
 @code{<#} and @code{#>}.  @cindex words, forgetting
   @cindex forgeting words
   
   @c  anton: other, maybe better places for this subsection: Defining Words;
   @c  Dictionary allocation.  At least a reference should be there.
   
 doc-~~  Forth allows you to forget words (and everything that was alloted in the
 doc-printdebugdata  dictonary after them) in a LIFO manner.
 doc-printdebugline  
   
 doc-see  
 doc-marker  doc-marker
   
   The most common use of this feature is during progam development: when
   you change a source file, forget all the words it defined and load it
   again (since you also forget everything defined after the source file
   was loaded, you have to reload that, too).  Note that effects like
   storing to variables and destroyed system words are not undone when you
   forget words.  With a system like Gforth, that is fast enough at
   starting up and compiling, I find it more convenient to exit and restart
   Gforth, as this gives me a clean slate.
   
 Here's an example of using @code{marker} at the start of a source file  Here's an example of using @code{marker} at the start of a source file
 that you are debugging; it ensures that you only ever have one copy of  that you are debugging; it ensures that you only ever have one copy of
Line 8799 
Line 8798 
 @end example  @end example
   
   
   @node Debugging, Assertions, Forgetting words, Programming Tools
   @subsection Debugging
   @cindex debugging
   
   Languages with a slow edit/compile/link/test development loop tend to
   require sophisticated tracing/stepping debuggers to facilate debugging.
   
   A much better (faster) way in fast-compiling languages is to add
   printing code at well-selected places, let the program run, look at
   the output, see where things went wrong, add more printing code, etc.,
   until the bug is found.
   
   The simple debugging aids provided in @file{debugs.fs}
   are meant to support this style of debugging.
   
   The word @code{~~} prints debugging information (by default the source
   location and the stack contents). It is easy to insert. If you use Emacs
   it is also easy to remove (@kbd{C-x ~} in the Emacs Forth mode to
   query-replace them with nothing). The deferred words
   @code{printdebugdata} and @code{printdebugline} control the output of
   @code{~~}. The default source location output format works well with
   Emacs' compilation mode, so you can step through the program at the
   source level using @kbd{C-x `} (the advantage over a stepping debugger
   is that you can step in any direction and you know where the crash has
   happened or where the strange data has occurred).
   
   doc-~~
   doc-printdebugdata
   doc-printdebugline
   
 @node Assertions, Singlestep Debugger, Debugging, Programming Tools  @node Assertions, Singlestep Debugger, Debugging, Programming Tools
 @subsection Assertions  @subsection Assertions
Line 9004 
Line 9032 
 ;                                  end-code  ;                                  end-code
 @end example  @end example
   
 @code{flush-icache} is always present. The other words are rarely used  @c anton: the following stuff is also in "Common Assembler", in less detail.
 and reside in @code{code.fs}, which is usually not loaded. You can load  
 it with @code{require code.fs}.  
   
 @cindex registers of the inner interpreter  @cindex registers of the inner interpreter
 In the assembly code you will want to refer to the inner interpreter's  In the assembly code you will want to refer to the inner interpreter's
Line 9014 
Line 9040 
 registers for temporary storage. Unfortunately, the register allocation  registers for temporary storage. Unfortunately, the register allocation
 is installation-dependent.  is installation-dependent.
   
 The easiest solution is to use explicit register declarations  In particular, @code{ip} (Forth instruction pointer) and @code{rp}
 (@pxref{Explicit Reg Vars, , Variables in Specified Registers, gcc.info,  (return stack pointer) are in different places in @code{gforth} and
 GNU C Manual}) for all of the inner interpreter's registers: You have to  @code{gforth-fast}.  This means that you cannot write a @code{NEXT}
 compile Gforth with @code{-DFORCE_REG} (configure option  routine that works on both versions; so for doing @code{NEXT}, I
 @code{--enable-force-reg}) and the appropriate declarations must be  recomment jumping to @code{' noop >code-address}, which contains nothing
 present in the @code{machine.h} file (see @code{mips.h} for an example;  but a @code{NEXT}.
 you can find a full list of all declarable register symbols with  
 @code{grep register engine.c}). If you give explicit registers to all  For general accesses to the inner interpreter's registers, the easiest
 variables that are declared at the beginning of @code{engine()}, you  solution is to use explicit register declarations (@pxref{Explicit Reg
 should be able to use the other caller-saved registers for temporary  Vars, , Variables in Specified Registers, gcc.info, GNU C Manual}) for
 storage. Alternatively, you can use the @code{gcc} option  all of the inner interpreter's registers: You have to compile Gforth
 @code{-ffixed-REG} (@pxref{Code Gen Options, , Options for Code  with @code{-DFORCE_REG} (configure option @code{--enable-force-reg}) and
 Generation Conventions, gcc.info, GNU C Manual}) to reserve a register  the appropriate declarations must be present in the @code{machine.h}
 (however, this restriction on register allocation may slow Gforth  file (see @code{mips.h} for an example; you can find a full list of all
 significantly).  declarable register symbols with @code{grep register engine.c}). If you
   give explicit registers to all variables that are declared at the
   beginning of @code{engine()}, you should be able to use the other
   caller-saved registers for temporary storage. Alternatively, you can use
   the @code{gcc} option @code{-ffixed-REG} (@pxref{Code Gen Options, ,
   Options for Code Generation Conventions, gcc.info, GNU C Manual}) to
   reserve a register (however, this restriction on register allocation may
   slow Gforth significantly).
   
 If this solution is not viable (e.g., because @code{gcc} does not allow  If this solution is not viable (e.g., because @code{gcc} does not allow
 you to explicitly declare all the registers you need), you have to find  you to explicitly declare all the registers you need), you have to find
Line 9084 
Line 9117 
 changed register assignment.  The stability of the register assignment  changed register assignment.  The stability of the register assignment
 is usually better if you build Gforth with @code{--enable-force-reg}.  is usually better if you build Gforth with @code{--enable-force-reg}.
   
 In particular, the resturn stack pointer and the instruction pointer are  In particular, the return stack pointer and the instruction pointer are
 in memory in @code{gforth}, and usually in registers in  in memory in @code{gforth}, and usually in registers in
 @code{gforth-fast}.  The most common use of these registers is to  @code{gforth-fast}.  The most common use of these registers is to
 dispatch to the next word (the @code{next} routine).  A portable way to  dispatch to the next word (the @code{next} routine).  A portable way to

Generate output suitable for use with a patch program
Legend:
Removed from v.1.76  
changed lines
  Added in v.1.77
CVS Admin

Powered by ViewCVS 1.0-dev 		(Powered by ViewCVS)

ViewCVS and CVS Help