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:
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.
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
Set up to enter the debugger when the current frame is exited.
Frames that invoke the debugger on exit are flagged with stars.
Don't enter the debugger when the current frame is exited. This
cancels a `b' command on a frame.
Read a Lisp expression in the minibuffer, evaluate it, and print
the value in the echo area. This is equivalent to the command
Terminate the program being debugged; return to top-level Emacs
If the debugger was entered due to a `C-g' but you really want to
quit, not to debug, use the `q' command.
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 126.96.36.199