(xemacs.info)Lisp Debug


Next: Lisp Interaction Prev: Lisp Eval Up: Running
Enter node , (file) or (file)node

22.5 The Emacs-Lisp Debugger
============================

XEmacs contains a debugger for Lisp programs executing inside it.  This
debugger is normally not used; many commands frequently get Lisp errors
when invoked in inappropriate contexts (such as `C-f' at the end of the
buffer) and it would be unpleasant to enter a special debugging mode in
this case.  When you want to make Lisp errors invoke the debugger, you
must set the variable `debug-on-error' to non-`nil'.  Quitting with
`C-g' is not considered an error, and `debug-on-error' has no effect on
the handling of `C-g'.  However, if you set `debug-on-quit' to be
non-`nil', `C-g' will invoke the debugger.  This can be useful for
debugging an infinite loop; type `C-g' once the loop has had time to
reach its steady state.  `debug-on-quit' has no effect on errors.

   You can make Emacs enter the debugger when a specified function is
called or at a particular place in Lisp code.  Use `M-x debug-on-entry'
with argument FUN-NAME to have Emacs enter the debugger as soon as
FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
function stop entering the debugger when called.  (Redefining the
function also does this.)  To enter the debugger from some other place
in Lisp code, you must insert the expression `(debug)' there and
install the changed code with `C-M-x'.  Note: Lisp Eval.

   When the debugger is entered, it displays the previously selected
buffer in one window and a buffer named `*Backtrace*' in another
window.  The backtrace buffer contains one line for each level of Lisp
function execution currently going on.  At the beginning of the buffer
is a message describing the reason that the debugger was invoked, for
example, an error message if it was invoked due to an error.

   The backtrace buffer is read-only and is in Backtrace mode, a special
major mode in which letters are defined as debugger commands.  The
usual Emacs editing commands are available; you can switch windows to
examine the buffer that was being edited at the time of the error, and
you can switch buffers, visit files, and perform any other editing
operations.  However, the debugger is a recursive editing level (Note:
Recursive Edit); it is a good idea to return to the backtrace buffer
and explicitly exit the debugger when you don't want to use it any
more.  Exiting the debugger kills the backtrace buffer.

   The contents of the backtrace buffer show you the functions that are
executing and the arguments that were given to them.  It also allows you
to specify a stack frame by moving point to the line describing that
frame.  The frame whose line point is on is considered the "current
frame".  Some of the debugger commands operate on the current frame.
Debugger commands are mainly used for stepping through code one
expression at a time.  Here is a list of them:

`c'
     Exit the debugger and continue execution.  In most cases,
     execution of the program continues as if the debugger had never
     been entered (aside from the effect of any variables or data
     structures you may have changed while inside the debugger).  This
     includes entry to the debugger due to function entry or exit,
     explicit invocation, and quitting or certain errors.  Most errors
     cannot be continued; trying to continue an error usually causes
     the same error to occur again.

`d'
     Continue execution, but enter the debugger the next time a Lisp
     function is called.  This allows you to step through the
     subexpressions of an expression, and see what the subexpressions
     do and what values they compute.

     When you enter the debugger this way, Emacs flags the stack frame
     for the function call from which you entered.  The same function
     is then called when you exit the frame.  To cancel this flag, use
     `u'.

`b'
     Set up to enter the debugger when the current frame is exited.
     Frames that invoke the debugger on exit are flagged with stars.

`u'
     Don't enter the debugger when the current frame is exited.  This
     cancels a `b' command on a frame.

`e'
     Read a Lisp expression in the minibuffer, evaluate it, and print
     the value in the echo area.  This is equivalent to the command
     `M-:'.

`q'
     Terminate the program being debugged; return to top-level Emacs
     command execution.

     If the debugger was entered due to a `C-g' but you really want to
     quit, not to debug, use the `q' command.

`r'
     Return a value from the debugger.  The value is computed by
     reading an expression with the minibuffer and evaluating it.

     The value returned by the debugger makes a difference when the
     debugger was invoked due to exit from a Lisp call frame (as
     requested with `b'); then the value specified in the `r' command
     is used as the value of that frame.

     The debugger's return value also matters with many errors.  For
     example, `wrong-type-argument' errors will use the debugger's
     return value instead of the invalid argument; `no-catch' errors
     will use the debugger value as a throw tag instead of the tag that
     was not found.  If an error was signaled by calling the Lisp
     function `signal', the debugger's return value is returned as the
     value of `signal'.


automatically generated by info2www version 1.2.2.9