@c  Copyright (c) 1994 William Schelter.

@node Debugging, Miscellaneous, System Definitions, Top
@chapter Debugging



@menu
* Source Level Debugging in Emacs::  
* Low Level Debug Functions::	
@end menu

@node Source Level Debugging in Emacs, Low Level Debug Functions, Debugging, Debugging
@section Source Level Debugging in Emacs

In emacs load (load "dbl.el") from the gcl/doc directory.
[ It also requires gcl.el from that directory.    Your system
administrator should do make in the doc directory, so that
these files are copied to the standard location.]

OVERVIEW:

   Lisp files loaded with si::nload will have source line information about
them recorded.  Break points may be set, and functions stepped.  Source code
will be automatically displayed in the other window, with a little arrow beside
the current line.  The backtrace (command :bt) will show line information and
you will get automatic display of the source as you move up and down the stack.

FUNCTIONS:
break points which have been set.
   si::nload (file)
      load a lisp file collecting source line information.
    
   si::break-function (function &optional line absolute)
     set up a breakpoint for FUNCTION at LINE relative to start or ABSOLUTE

EMACS COMMANDS:
M-x dbl makes a dbl buffer, suitable for running an inferior gcl.
It has special keybindings for stepping and viewing sources.

Inferior Dbl Mode:
Major mode for interacting with an inferior Dbl process.
The following commands are available:

C-c l           dbl-find-line

ESC d           dbl-:down
ESC u           dbl-:up
ESC c           dbl-:r
ESC n           dbl-:next
ESC i           dbl-:step
ESC s           dbl-:step


M-x dbl-display-frame displays in the other window
the last line referred to in the dbl buffer.

ESC i and ESC n in the dbl window,
call dbl to step and next and then update the other window
with the current file and position.

If you are in a source file, you may select a point to break
at, by doing C-x SPC.

Commands:
Many commands are inherited from shell mode. 
Additionally we have:

M-x dbl-display-frame display frames file in other window
ESC i advance one line in program
ESC n advance one line in program (skip over calls).
M-x send-dbl-command used for special printing of an arg at the current point.
C-x SPACE sets break point at current line.

----------------------------

   When visiting a lisp buffer (if gcl.el is loaded in your emacs) the command
c-m-x evaluates the current defun into the process running in the other window.
Line information will be kept.  This line information allows you to set break
points at a given line (by typing C-x \space on the line in the source file
where you want the break to occur.  Once stopped within a function you may
single step with M-s.  This moves one line at a time in the source code,
displaying a little arrow beside your current position.  M-c is like M-s,
except that function invocations are skipped over, rather than entered into.
M-c continues execution.

   Keywords typed at top level, in the debug loop have
a special meaning:
@itemize

@item
:delete  [n1] [n2] .. -- delete all break points or just n1,n2
@item
:disable [n1] [n2] .. -- disable all break points or just n1,n2
@item
:enable  [n1] [n2] .. -- enable all break points or just n1,n2
@item
:info  [:bkpt]      --print information about 
@item
:break [fun] [line] -- break at the current location, or if
     fun is supplied in fun.   Break  at the beginning unless a
     line offset from the beginning of fun is supplied.
@item
:fr [n] go to frame n   When in frame n, if the frame is interpreted,
    typing the name of locals, will print their values.   If it is compiled
    you must use (si::loc j) to print `locj'.   Autodisplay of the source
    will take place if it is interpreted and the line can be determined.
@item
:up [n] go up n frames from the current frame.
@item
:down [n] go down n frames
@item
:bt [n] back trace starting at the current frame and going to top level
     If n is specified show only n frames.
@item
:r  If stopped in a function resume.   If at top level in the dbl
   loop, exit and resume an outer loop.
@item
:q  quit the computation back to top level dbl loop.
@item
:step step to the next line with line information
@item
:next  step to the next line with line information skipping over function
    invocations.

@end itemize
Files:  debug.lsp  dbl.el    gcl.el

@node Low Level Debug Functions,  , Source Level Debugging in Emacs, Debugging
@section Low Level Debug Functions

Use the following functions to directly access GCL stacks.
@example
(SI:VS i)	Returns the i-th entity in VS.
(SI:IHS-VS i)	Returns the VS index of the i-th entity in IHS.
(SI:IHS-FUN i)	Returns the function of the i-th entity in IHS.
(SI:FRS-VS i)	Returns the VS index of the i-th entity in FRS.
(SI:FRS-BDS i)	Returns the BDS index of the i-th entity in FRS.
(SI:FRS-IHS i)	Returns the IHS index of the i-th entity in FRS.
(SI:BDS-VAR i)	Returns the symbol of the i-th entity in BDS.
(SI:BDS-VAL i)	Returns the value of the i-th entity in BDS.

(SI:SUPER-GO i tag)
	Jumps to the specified tag established by the TAGBODY frame at
	FRS[i].  Both arguments are evaluated.  If FRS[i] happens to be
	a non-TAGBODY frame, then (THROW (SI:IHS-TAG i) (VALUES)) is
	performed.
@end example
