@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.   You may
start your favorite gcl program in the dbl shell buffer.

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 @asis

@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
