18.1.6 Using the Debugger

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 this buffer is a message describing the reason that the debugger was invoked (such as the error message and associated data, if it was invoked due to an error).

The backtrace buffer is read-only and uses a special major mode, Debugger mode, in which letters are defined as debugger commands. The usual Emacs editing commands are available; thus, you can switch windows to examine the buffer that was being edited at the time of the error, switch buffers, visit files, or do any other sort of editing. However, the debugger is a recursive editing level (see Recursive Editing) and it is wise to go back to the backtrace buffer and exit the debugger (with the q command) when you are finished with it. Exiting the debugger gets out of the recursive edit and buries the backtrace buffer. (You can customize what the q command does with the backtrace buffer by setting the variable debugger-bury-or-kill. For example, set it to kill if you prefer to kill the buffer rather than bury it. Consult the variable’s documentation for more possibilities.)

When the debugger has been entered, the debug-on-error variable is temporarily set according to eval-expression-debug-on-error. If the latter variable is non-nil, debug-on-error will temporarily be set to t. This means that any further errors that occur while doing a debugging session will (by default) trigger another backtrace. If this is not what you want, you can either set eval-expression-debug-on-error to nil, or set debug-on-error to nil in debugger-mode-hook.

The debugger itself must be run byte-compiled, since it makes assumptions about the state of the Lisp interpreter. These assumptions are false if the debugger is running interpreted.