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.
This commit is contained in:
Chong Yidong
parent
5eac0c026f
commit
355cabc6c7
6 changed files with 119 additions and 124 deletions
|
|
@ -1,3 +1,15 @@
|
|||
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.
|
||||
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.
|
||||
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 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.
|
||||
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.
|
||||
|
||||
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,51 +111,49 @@ 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}.
|
||||
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 will need to change this list in order to debug
|
||||
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}.
|
||||
|
||||
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
|
||||
|
||||
@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.
|
||||
@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 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}.
|
||||
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:} 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}.
|
||||
@end defopt
|
||||
@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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue