@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/debugging
-@node Debugging, Read and Print, Advising Functions, Top
+@node Debugging
@chapter Debugging Lisp Programs
There are several ways to find and investigate problems in an Emacs
any of the regular expressions, then that error does not enter the
debugger.
-The normal value of this variable lists several errors that happen
-often during editing but rarely result from bugs in Lisp programs.
-However, ``rarely'' is not ``never''; if your program fails with an
-error that matches this list, you may try changing this list to debug
-the error. The easiest way is usually to set
-@code{debug-ignored-errors} to @code{nil}.
+The normal value of this variable includes @code{user-error}, as well
+as several errors that happen often during editing but rarely result
+from bugs in Lisp programs. However, ``rarely'' is not ``never''; if
+your program fails with an error that matches this list, you may try
+changing this list to debug the error. The easiest way is usually to
+set @code{debug-ignored-errors} to @code{nil}.
@end defopt
@defopt eval-expression-debug-on-error
@code{inhibit-quit} is set and Emacs is not otherwise responding.
@end defopt
+@cindex message, finding what causes a particular message
+@defvar debug-on-message
+If you set @code{debug-on-message} to a regular expression,
+Emacs will enter the debugger if it displays a matching message in the
+echo area. For example, this can be useful when trying to find the
+cause of a particular message.
+@end defvar
+
To debug an error that happens during loading of the init
file, use the option @samp{--debug-init}. This binds
@code{debug-on-error} to @code{t} while loading the init file, and
program!) The most common suitable places are inside a @code{progn} or
an implicit @code{progn} (@pxref{Sequencing}).
+ If you don't know exactly where in the source code you want to put
+the debug statement, but you want to display a backtrace when a
+certain message is displayed, you can set @code{debug-on-message} to a
+regular expression matching the desired message.
+
@node Using Debugger
@subsection Using the Debugger
When the debugger is entered, it displays the previously selected
-buffer in one window and a buffer named @samp{*Backtrace*} in another
+buffer in one window and a buffer named @file{*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).
+@vindex debugger-bury-or-kill
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
the debugger is a recursive editing level (@pxref{Recursive Editing})
and it is wise to go back to the backtrace buffer and exit the debugger
(with the @kbd{q} command) when you are finished with it. Exiting
-the debugger gets out of the recursive edit and kills the backtrace
-buffer.
+the debugger gets out of the recursive edit and buries the backtrace
+buffer. (You can customize what the @kbd{q} command does with the
+backtrace buffer by setting the variable @code{debugger-bury-or-kill}.
+For example, set it to @code{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 @code{debug-on-error}
variable is temporarily set according to
non-@code{nil}, @code{debug-on-error} will temporarily be set to
@code{t}. This means that any further errors that occur while doing a
debugging session will (by default) trigger another backtrace. If
-this is not want you want, you can either set
+this is not what you want, you can either set
@code{eval-expression-debug-on-error} to @code{nil}, or set
@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}.
@item R
Like @kbd{e}, but also save the result of evaluation in the
-buffer @samp{*Debugger-record*}.
+buffer @file{*Debugger-record*}.
@item q
Terminate the program being debugged; return to top-level Emacs
Here we describe in full detail the function @code{debug} that is used
to invoke the debugger.
-@defun debug &rest debugger-args
+@deffn Command debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
-named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
+named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second
recursive entry to the debugger, etc.), and fills it with information
about the stack of Lisp function calls. It then enters a recursive
edit, showing the backtrace buffer in Debugger mode.
way the function @code{debug} can return to its caller.
The use of the @var{debugger-args} is that @code{debug} displays the
-rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
+rest of its arguments at the top of the @file{*Backtrace*} buffer, so
that the user can see them. Except as described below, this is the
@emph{only} way these arguments are used.
display messages---for example, to remind yourself of the conditions
under which @code{debug} is called.
@end table
-@end defun
+@end deffn
@node Internals of Debugger
@subsection Internals of the Debugger
@cindex call stack
This function prints a trace of Lisp function calls currently active.
This is the function used by @code{debug} to fill up the
-@samp{*Backtrace*} buffer. It is written in C, since it must have access
+@file{*Backtrace*} buffer. It is written in C, since it must have access
to the stack to determine which function calls are active. The return
value is always @code{nil}.
HCoop / bpt / emacs.git / blobdiff