Commit 355cabc6 authored by Chong Yidong's avatar Chong Yidong

Update Debugging chapter of Lisp manual.

* doc/emacs/debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
(Error Debugging): Note that debug-ignored-errors overrides list
values of debug-on-error too.  Add xref to Signaling Errors.  Note
that debug-on-signal is not customizable.  Mention
condition-case-unless-debug.
(Compilation Errors): Node deleted.

* doc/emacs/compile.texi (Compiler Errors): Move a paragraph here from
deleted node Compilation Errors.
parent 5eac0c02
2012-02-11 Chong Yidong <cyd@gnu.org>
* debugging.texi (Debugging): Copyedits. Describe testcover, ERT.
(Error Debugging): Note that debug-ignored-errors overrides list
values of debug-on-error too. Add xref to Signaling Errors. Note
that debug-on-signal is not customizable. Mention
condition-case-unless-debug.
(Compilation Errors): Node deleted.
* compile.texi (Compiler Errors): Move a paragraph here from
deleted node Compilation Errors.
2012-02-10 Leo Liu <sdl.web@gmail.com>
* control.texi (Handling Errors): Change condition-case-no-debug
......
......@@ -445,13 +445,22 @@ to what @code{eval-when-compile} does.
Byte compilation outputs all errors and warnings into the buffer
@samp{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
commands for operating on compiler diagnostics work properly on
these messages.
However, the warnings about functions that were used but not
defined are always ``located'' at the end of the file, so these
commands won't find the places they are really used. To do that,
you must search for the function names.
commands for operating on compiler diagnostics work properly on these
messages.
When an error is due to invalid syntax in the program, the byte
compiler might get confused about the errors' exact location. One way
to investigate is to switch to the buffer @w{@samp{*Compiler Input*}}.
(This buffer name starts with a space, so it does not show up in
@kbd{M-x list-buffers}.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read;
the cause of the error might be nearby. @xref{Syntax Errors}, for
some tips for locating syntax errors.
When the byte compiler warns about functions that were used but not
defined, it always reports the line number for the end of the file,
not the locations where the missing functions were called. To find
the latter, you must search for the function names.
You can suppress the compiler warning for calling an undefined
function @var{func} by conditionalizing the function call on an
......
......@@ -6,41 +6,46 @@
@node Debugging, Read and Print, Advising Functions, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
depending on what you are doing with the program when the problem appears.
There are several ways to find and investigate problems in an Emacs
Lisp program.
@itemize @bullet
@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,
Edebug. This chapter describes both of them.
If a problem occurs when you run the program, you can use the built-in
Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or
alter its internal state.
@item
If the problem is syntactic, so that Lisp cannot even read the program,
you can use the Emacs facilities for editing Lisp to localize it.
You can use Edebug, a source-level debugger for Emacs Lisp.
@item
If the problem occurs when trying to compile the program with the byte
compiler, you need to know how to examine the compiler's input buffer.
If a syntactic problem is preventing Lisp from even reading the
program, you can locate it using Lisp editing commands.
@item
You can look at the error and warning messages produced by the byte
compiler when it compiles the program. @xref{Compiler Errors}.
@item
You can use the Testcover package to perform coverage testing on the
program.
@item
You can use the ERT package to write regression tests for the program.
@xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
@end itemize
Other useful tools for debugging input and output problems are the
dribble file (@pxref{Terminal Input}) and the @code{open-termscript}
function (@pxref{Terminal Output}).
@menu
* Debugger:: How the Emacs Lisp debugger is implemented.
* Debugger:: A debugger for the Emacs Lisp evaluator.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in byte compilation.
@end menu
Another useful debugging tool is the dribble file. When a dribble
file is open, Emacs copies all keyboard input characters to that file.
Afterward, you can examine the file to find out what input was used.
@xref{Terminal Input}.
For debugging problems in terminal descriptions, the
@code{open-termscript} function can be useful. @xref{Terminal Output}.
@node Debugger
@section The Lisp Debugger
@cindex debugger for Emacs Lisp
......@@ -76,25 +81,29 @@ happens. This allows you to investigate the immediate causes of the
error.
However, entry to the debugger is not a normal consequence of an
error. Many commands frequently cause Lisp errors when invoked
inappropriately, and during ordinary editing it would be very
inconvenient to enter the debugger each time this happens. So if you
want errors to enter the debugger, set the variable
@code{debug-on-error} to non-@code{nil}. (The command
@code{toggle-debug-on-error} provides an easy way to do this.)
error. Many commands signal Lisp errors when invoked inappropriately,
and during ordinary editing it would be very inconvenient to enter the
debugger each time this happens. So if you want errors to enter the
debugger, set the variable @code{debug-on-error} to non-@code{nil}.
(The command @code{toggle-debug-on-error} provides an easy way to do
this.)
@defopt debug-on-error
This variable determines whether the debugger is called when an error
is signaled and not handled. If @code{debug-on-error} is @code{t},
all kinds of errors call the debugger, except those listed in
@code{debug-ignored-errors} (see below). If it is @code{nil}, none
call the debugger. (Note that @code{eval-expression-debug-on-error}
affects the setting of this variable in some cases; see below.)
call the debugger.
The value can also be a list of error conditions (@pxref{Signaling
Errors}). Then the debugger is called only for error conditions in
this list (except those also listed in @code{debug-ignored-errors}).
For example, if you set @code{debug-on-error} to the list
@code{(void-variable)}, the debugger is only called for errors about a
variable that has no value.
The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
Note that @code{eval-expression-debug-on-error} overrides this
variable in some cases; see below.
When this variable is non-@code{nil}, Emacs does not create an error
handler around process filter functions and sentinels. Therefore,
......@@ -102,52 +111,50 @@ errors in these functions also invoke the debugger. @xref{Processes}.
@end defopt
@defopt debug-ignored-errors
This variable specifies certain kinds of errors that should not enter
the debugger. Its value is a list of error condition symbols and/or
regular expressions. If the error has any of those condition symbols,
or if the error message matches any of the regular expressions, then
that error does not enter the debugger, regardless of the value of
@code{debug-on-error}.
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 will need to change this list in order to debug
This variable specifies errors which should not enter the debugger,
regardless of the value of @code{debug-on-error}. Its value is a list
of error condition symbols and/or regular expressions. If the error
has any of those condition symbols, or if the error message matches
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}.
@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
If this variable has a non-@code{nil} value (the default), running the
command @code{eval-expression} causes @code{debug-on-error} to be
temporarily bound to to @code{t}. @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
words, @code{condition-case} gets a chance to handle the error before
the debugger gets a chance.
If you set @code{debug-on-signal} to a non-@code{nil} value, then the
debugger gets the first chance at every error; an error will invoke the
debugger regardless of any @code{condition-case}, if it fits the
criteria specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medicine! Various parts of
Emacs handle errors in the normal course of affairs, and you may not
even realize that errors happen there. If you set
@code{debug-on-signal} to a non-@code{nil} value, those errors will
enter the debugger.
@strong{Warning:} @code{debug-on-signal} has no effect when
@code{debug-on-error} is @code{nil}.
If @code{eval-expression-debug-on-error} is @code{nil}, then the value
of @code{debug-on-error} is not changed during @code{eval-expression}.
@end defopt
@defvar debug-on-signal
Normally, errors caught by @code{condition-case} never invoke the
debugger. The @code{condition-case} gets a chance to handle the error
before the debugger gets a chance.
If you change @code{debug-on-signal} to a non-@code{nil} value, the
debugger gets the first chance at every error, regardless of the
presence of @code{condition-case}. (To invoke the debugger, the error
must still fulfill the criteria specified by @code{debug-on-error} and
@code{debug-ignored-errors}.)
@strong{Warning:} Setting this variable to non-@code{nil} may have
annoying effects. Various parts of Emacs catch errors in the normal
course of affairs, and you may not even realize that errors happen
there. If you need to debug code wrapped in @code{condition-case},
consider using @code{condition-case-unless-debug} (@pxref{Handling
Errors}).
@end defvar
@defopt debug-on-event
If you set @code{debug-on-event} to a special event (@pxref{Special
Events}), Emacs will try to enter the debugger as soon as it receives
......@@ -171,27 +178,26 @@ init file.
@cindex stopping an infinite loop
When a program loops infinitely and fails to return, your first
problem is to stop the loop. On most operating systems, you can do this
with @kbd{C-g}, which causes a @dfn{quit}.
problem is to stop the loop. On most operating systems, you can do
this with @kbd{C-g}, which causes a @dfn{quit}. @xref{Quitting}.
Ordinary quitting gives no information about why the program was
looping. To get more information, you can set the variable
@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
considered an error, and @code{debug-on-error} has no effect on the
handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on
errors.
@code{debug-on-quit} to non-@code{nil}. Once you have the debugger
running in the middle of the infinite loop, you can proceed from the
debugger using the stepping commands. If you step through the entire
loop, you may get enough information to solve the problem.
Once you have the debugger running in the middle of the infinite loop,
you can proceed from the debugger using the stepping commands. If you
step through the entire loop, you will probably get enough information
to solve the problem.
Quitting with @kbd{C-g} is not considered an error, and
@code{debug-on-error} has no effect on the handling of @kbd{C-g}.
Likewise, @code{debug-on-quit} has no effect on errors.
@defopt debug-on-quit
This variable determines whether the debugger is called when @code{quit}
is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
then the debugger is called whenever you quit (that is, type @kbd{C-g}).
If @code{debug-on-quit} is @code{nil}, then the debugger is not called
when you quit. @xref{Quitting}.
This variable determines whether the debugger is called when
@code{quit} is signaled and not handled. If @code{debug-on-quit} is
non-@code{nil}, then the debugger is called whenever you quit (that
is, type @kbd{C-g}). If @code{debug-on-quit} is @code{nil} (the
default), then the debugger is not called when you quit.
@end defopt
@node Function Debugging
......@@ -337,8 +343,8 @@ 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
name, or move to it and type @key{RET}, to visit the source code.
where its source code is located. You can click with the mouse on
that name, or move to it and type @key{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
......@@ -790,29 +796,3 @@ never return. If it ever does return, you get a run-time error.
Edebug also has a coverage testing feature (@pxref{Coverage
Testing}). These features partly duplicate each other, and it would
be cleaner to combine them.
@node Compilation Errors
@section Debugging Problems in Compilation
@cindex debugging byte compilation problems
When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling. The compiler prints a
suitable error message in the @samp{*Compile-Log*} buffer, and then
stops. The message may state a function name in which the error was
found, or it may not. Either way, here is how to find out where in the
file the error occurred.
What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
(Note that the buffer name starts with a space, so it does not show
up in @kbd{M-x list-buffers}.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read.
If the error was due to invalid Lisp syntax, point shows exactly where
the invalid syntax was @emph{detected}. The cause of the error is not
necessarily near by! Use the techniques in the previous section to find
the error.
If the error was detected while compiling a form that had been read
successfully, then point is located at the end of the form. In this
case, this technique can't localize the error precisely, but can still
show you which function to check.
......@@ -552,12 +552,10 @@ Advising Emacs Lisp Functions
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
* Debugger:: A debugger for the Emacs Lisp evaluator.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in
byte compilation.
The Lisp Debugger
......
......@@ -572,12 +572,10 @@ Advising Emacs Lisp Functions
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
* Debugger:: A debugger for the Emacs Lisp evaluator.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in
byte compilation.
The Lisp Debugger
......
......@@ -571,12 +571,10 @@ Advising Emacs Lisp Functions
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
* Debugger:: A debugger for the Emacs Lisp evaluator.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in
byte compilation.
The Lisp Debugger
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment