@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Advising Functions, Top
@item
If the problem occurs when you run the program, you can use a Lisp
debugger to investigate what is happening during execution. In addition
-to the ordinary debugger, Emacs comes with a source level debugger,
+to the ordinary debugger, Emacs comes with a source-level debugger,
Edebug. This chapter describes both of them.
@item
@code{debug-ignored-errors} to @code{nil}.
@end defopt
+@defopt eval-expression-debug-on-error
+If this variable has a non-@code{nil} value, then
+@code{debug-on-error} is set to @code{t} when evaluating with the
+command @code{eval-expression}. If
+@code{eval-expression-debug-on-error} is @code{nil}, then the value of
+@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating
+Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
+@end defopt
+
@defopt debug-on-signal
Normally, errors that are caught by @code{condition-case} never run the
debugger, even if @code{debug-on-error} is non-@code{nil}. In other
function, and then step through its caller.
@deffn Command debug-on-entry function-name
-This function requests @var{function-name} to invoke the debugger each time
-it is called. It works by inserting the form @code{(debug 'debug)} into
-the function definition as the first form.
-
-Any function defined as Lisp code may be set to break on entry,
-regardless of whether it is interpreted code or compiled code. If the
-function is a command, it will enter the debugger when called from Lisp
-and when called interactively (after the reading of the arguments). You
-can't debug primitive functions (i.e., those written in C) this way.
+This function requests @var{function-name} to invoke the debugger each
+time it is called. It works by inserting the form
+@code{(implement-debug-on-entry)} into the function definition as the
+first form.
+
+Any function or macro defined as Lisp code may be set to break on
+entry, regardless of whether it is interpreted code or compiled code.
+If the function is a command, it will enter the debugger when called
+from Lisp and when called interactively (after the reading of the
+arguments). You can also set debug-on-entry for primitive functions
+(i.e., those written in C) this way, but it only takes effect when the
+primitive is called from Lisp code. Debug-on-entry is not allowed for
+special forms.
When @code{debug-on-entry} is called interactively, it prompts for
@var{function-name} in the minibuffer. If the function is already set
@group
------ Buffer: *Backtrace* ------
-Entering:
+Debugger entered--entering a function:
* fact(3)
- eval-region(4870 4878 t)
- byte-code("...")
+ eval((fact 3))
+ eval-last-sexp-1(nil)
eval-last-sexp(nil)
- (let ...)
- eval-insert-last-sexp(nil)
-* call-interactively(eval-insert-last-sexp)
+ call-interactively(eval-last-sexp)
------ Buffer: *Backtrace* ------
@end group
@end example
@end deffn
-@deffn Command cancel-debug-on-entry function-name
+@deffn Command cancel-debug-on-entry &optional function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
@var{function-name} in the minibuffer. If @var{function-name} is
-@code{nil} or the empty string, it cancels break-on-entry for all
-functions.
-
+omitted or @code{nil}, it cancels break-on-entry for all functions.
Calling @code{cancel-debug-on-entry} does nothing to a function which is
-not currently set up to break on entry. It always returns
-@var{function-name}.
+not currently set up to break on entry.
@end deffn
@node Explicit Debug
place where the Lisp interpreter records information about a particular
invocation of a function.) The frame whose line point is on is
considered the @dfn{current frame}. Some of the debugger commands
-operate on the current frame.
+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 @kbd{Mouse-2} on that
itself. These assumptions are false if the debugger is running
interpreted.
-@need 3000
-
@node Debugger Commands
@subsection Debugger Commands
@cindex debugger command list
byte-compiled function. If you would like to step through a
byte-compiled function, replace it with an interpreted definition of
the same function. (To do this, visit the source for the function and
-type @kbd{C-M-x} on its definition.)
+type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
+to step through a primitive function.
Here is a list of Debugger mode commands:
cancels a @kbd{b} command on that frame. The visible effect is to
remove the star from the line in the backtrace buffer.
+@item j
+Flag the current frame like @kbd{b}. Then continue execution like
+@kbd{c}, but temporarily disable break-on-entry for all functions that
+are set up to do so by @code{debug-on-entry}.
+
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
value in the echo area. The debugger alters certain important
effect as @kbd{c}, and the specified return value does not matter.
You can't use @kbd{r} when the debugger was entered due to an error.
+
+@item l
+Display a list of functions that will invoke the debugger when called.
+This is a list of functions that are set to break on entry by means of
+@code{debug-on-entry}. @strong{Warning:} if you redefine such a
+function and thus cancel the effect of @code{debug-on-entry}, it may
+erroneously show up in this list.
@end table
@node Invoking the Debugger
about the stack of Lisp function calls. It then enters a recursive
edit, showing the backtrace buffer in Debugger mode.
-The Debugger mode @kbd{c} and @kbd{r} commands exit the recursive edit;
-then @code{debug} switches back to the previous buffer and returns to
-whatever called @code{debug}. This is the only way the function
-@code{debug} can return to its caller.
+The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
+the recursive edit; then @code{debug} switches back to the previous
+buffer and returns to whatever called @code{debug}. This is the only
+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
@table @code
@item lambda
@cindex @code{lambda} in debug
-A first argument of @code{lambda} means @code{debug} was called because
-of entry to a function when @code{debug-on-next-call} was
-non-@code{nil}. The debugger displays @samp{Entering:} as a line of
-text at the top of the buffer.
+A first argument of @code{lambda} means @code{debug} was called
+because of entry to a function when @code{debug-on-next-call} was
+non-@code{nil}. The debugger displays @samp{Debugger
+entered--entering a function:} as a line of text at the top of the
+buffer.
@item debug
-@code{debug} as first argument indicates a call to @code{debug} because
+@code{debug} as first argument means @code{debug} was called because
of entry to a function that was set to debug on entry. The debugger
-displays @samp{Entering:}, just as in the @code{lambda} case. It also
-marks the stack frame for that function so that it will invoke the
-debugger when exited.
+displays the string @samp{Debugger entered--entering a function:},
+just as in the @code{lambda} case. It also marks the stack frame for
+that function so that it will invoke the debugger when exited.
@item t
When the first argument is @code{t}, this indicates a call to
-@code{debug} due to evaluation of a list form when
-@code{debug-on-next-call} is non-@code{nil}. The debugger displays the
-following as the top line in the buffer:
-
-@smallexample
-Beginning evaluation of function call form:
-@end smallexample
+@code{debug} due to evaluation of a function call form when
+@code{debug-on-next-call} is non-@code{nil}. The debugger displays
+@samp{Debugger entered--beginning evaluation of function call form:}
+as the top line in the buffer.
@item exit
-When the first argument is @code{exit}, it indicates the exit of a stack
-frame previously marked to invoke the debugger on exit. The second
-argument given to @code{debug} in this case is the value being returned
-from the frame. The debugger displays @samp{Return value:} in the top
-line of the buffer, followed by the value being returned.
+When the first argument is @code{exit}, it indicates the exit of a
+stack frame previously marked to invoke the debugger on exit. The
+second argument given to @code{debug} in this case is the value being
+returned from the frame. The debugger displays @samp{Debugger
+entered--returning value:} in the top line of the buffer, followed by
+the value being returned.
@item error
@cindex @code{error} in debug
When the first argument is @code{error}, the debugger indicates that
-it is being entered because an error or @code{quit} was signaled and not
-handled, by displaying @samp{Signaling:} followed by the error signaled
-and any arguments to @code{signal}. For example,
+it is being entered because an error or @code{quit} was signaled and
+not handled, by displaying @samp{Debugger entered--Lisp error:}
+followed by the error signaled and any arguments to @code{signal}.
+For example,
@example
@group
@group
------ Buffer: *Backtrace* ------
-Signaling: (arith-error)
+Debugger entered--Lisp error: (arith-error)
/(1 0)
...
------ Buffer: *Backtrace* ------
The first argument that Lisp hands to the function indicates why it
was called. The convention for arguments is detailed in the description
-of @code{debug}.
+of @code{debug} (@pxref{Invoking the Debugger}).
@end defvar
@deffn Command backtrace
(save-excursion ...)
(let ...)
(with-output-to-temp-buffer ...)
- eval-region(1973 2142 #<buffer *scratch*>)
- byte-code("... for eval-print-last-sexp ...")
+ eval((with-output-to-temp-buffer ...))
+ eval-last-sexp-1(nil)
@group
- eval-print-last-sexp(nil)
-* call-interactively(eval-print-last-sexp)
+ eval-last-sexp(nil)
+ call-interactively(eval-last-sexp)
----------- Buffer: backtrace-output ------------
@end group
@end smallexample
-
-The character @samp{*} indicates a frame whose debug-on-exit flag is
-set.
@end deffn
@ignore @c Not worth mentioning
The first step is to find the defun that is unbalanced. If there is
an excess open parenthesis, the way to do this is to go to the end of
-the file and type @kbd{C-u C-M-u}. This will move you to the beginning
-of the defun that is unbalanced.
+the file and type @kbd{C-u C-M-u}. This will move you to the
+beginning of the first defun that is unbalanced.
The next step is to determine precisely what is wrong. There is no
way to be sure of this except by studying the program, but often the
@node Excess Close
@subsection Excess Close Parentheses
- To deal with an excess close parenthesis, first go to the beginning of
-the file, then type @kbd{C-u -1 C-M-u} to find the end of the unbalanced
-defun.
+ To deal with an excess close parenthesis, first go to the beginning
+of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
+unbalanced defun.
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
at the beginning of that defun. This will leave you somewhere short of