Debugging
*********

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:

  :delete  [n1] [n2] .. -- delete all break points or just n1,n2

  :disable [n1] [n2] .. -- disable all break points or just n1,n2

  :enable  [n1] [n2] .. -- enable all break points or just n1,n2

  :info  [:bkpt]      --print information about

  :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.

  :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.

  :up [n] go up n frames from the current frame.

  :down [n] go down n frames

  :bt [n] back trace starting at the current frame and going to top level If n is specified show only n frames.

  :r  If stopped in a function resume.   If at top level in the dbl loop, exit and resume an outer loop.

  :q  quit the computation back to top level dbl loop.

  :step step to the next line with line information

  :next  step to the next line with line information skipping over function invocations.

Files:  debug.lsp  dbl.el    gcl.el

Low Level Debug Functions
=========================

Use the following functions to directly access GCL stacks.

     (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.