From 355cabc6c7c568a89a464c89c3110db4194ec08a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 11 Feb 2012 14:17:22 +0800 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 12 +++ doc/lispref/compile.texi | 23 +++-- doc/lispref/debugging.texi | 204 ++++++++++++++++++++------------------------- doc/lispref/elisp.texi | 4 +- doc/lispref/vol1.texi | 4 +- doc/lispref/vol2.texi | 4 +- 6 files changed, 123 insertions(+), 128 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index d8e322790e7..5f0bf3fb694 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,15 @@ +2012-02-11 Chong Yidong + + * 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 * control.texi (Handling Errors): Change condition-case-no-debug diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 545f05d9d57..90d038c29d6 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -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 diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index cc92fc225f9..db5e4279dc7 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -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. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a925f3865a4..42c3613dd0b 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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 diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 31055bd03fe..cc96726745f 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -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 diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 92f049135a1..33246cb567d 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -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 -- 2.11.4.GIT