22.5 The Emacs-Lisp Debugger

SXEmacs 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. See 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 (see 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.