Info Catalog elisp: Explicit Debug elisp: Debugger elisp: Debugger Commands

elisp: Using Debugger

 
 17.1.5 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 (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 backtrace buffer shows you the functions that are executing and
 their argument values.  It also allows you to specify a stack frame by
 moving point to the line describing that frame.  (A stack frame is the
 place where the Lisp interpreter records information about a particular
 invocation of a function.)  The frame whose line point is on is
 considered the “current frame”.  Some of the debugger commands operate
 on the current frame.  If a line starts with a star, that means that
 exiting that frame will call the debugger again.  This is useful for
 examining the return value of a function.
 
    If a function name is underlined, that means the debugger knows where
 its source code is located.  You can click with the mouse on that name,
 or move to it and type <RET>, to visit the source code.
 
    The debugger itself must be run byte-compiled, since it makes
 assumptions about how many stack frames are used for the debugger
 itself.  These assumptions are false if the debugger is running
 interpreted.
 

Info Catalog elisp: Explicit Debug elisp: Debugger elisp: Debugger Commands