| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Emacs Lisp Reference Manual. |
| 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, |
| 4 | @c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. |
| 5 | @c See the file elisp.texi for copying conditions. |
| 6 | @setfilename ../info/debugging |
| 7 | @node Debugging, Read and Print, Advising Functions, Top |
| 8 | @chapter Debugging Lisp Programs |
| 9 | |
| 10 | There are three ways to investigate a problem in an Emacs Lisp program, |
| 11 | depending on what you are doing with the program when the problem appears. |
| 12 | |
| 13 | @itemize @bullet |
| 14 | @item |
| 15 | If the problem occurs when you run the program, you can use a Lisp |
| 16 | debugger to investigate what is happening during execution. In addition |
| 17 | to the ordinary debugger, Emacs comes with a source-level debugger, |
| 18 | Edebug. This chapter describes both of them. |
| 19 | |
| 20 | @item |
| 21 | If the problem is syntactic, so that Lisp cannot even read the program, |
| 22 | you can use the Emacs facilities for editing Lisp to localize it. |
| 23 | |
| 24 | @item |
| 25 | If the problem occurs when trying to compile the program with the byte |
| 26 | compiler, you need to know how to examine the compiler's input buffer. |
| 27 | @end itemize |
| 28 | |
| 29 | @menu |
| 30 | * Debugger:: How the Emacs Lisp debugger is implemented. |
| 31 | * Edebug:: A source-level Emacs Lisp debugger. |
| 32 | * Syntax Errors:: How to find syntax errors. |
| 33 | * Test Coverage:: Ensuring you have tested all branches in your code. |
| 34 | * Compilation Errors:: How to find errors that show up in byte compilation. |
| 35 | @end menu |
| 36 | |
| 37 | Another useful debugging tool is the dribble file. When a dribble |
| 38 | file is open, Emacs copies all keyboard input characters to that file. |
| 39 | Afterward, you can examine the file to find out what input was used. |
| 40 | @xref{Terminal Input}. |
| 41 | |
| 42 | For debugging problems in terminal descriptions, the |
| 43 | @code{open-termscript} function can be useful. @xref{Terminal Output}. |
| 44 | |
| 45 | @node Debugger |
| 46 | @section The Lisp Debugger |
| 47 | @cindex debugger |
| 48 | @cindex Lisp debugger |
| 49 | @cindex break |
| 50 | |
| 51 | The ordinary @dfn{Lisp debugger} provides the ability to suspend |
| 52 | evaluation of a form. While evaluation is suspended (a state that is |
| 53 | commonly known as a @dfn{break}), you may examine the run time stack, |
| 54 | examine the values of local or global variables, or change those values. |
| 55 | Since a break is a recursive edit, all the usual editing facilities of |
| 56 | Emacs are available; you can even run programs that will enter the |
| 57 | debugger recursively. @xref{Recursive Editing}. |
| 58 | |
| 59 | @menu |
| 60 | * Error Debugging:: Entering the debugger when an error happens. |
| 61 | * Infinite Loops:: Stopping and debugging a program that doesn't exit. |
| 62 | * Function Debugging:: Entering it when a certain function is called. |
| 63 | * Explicit Debug:: Entering it at a certain point in the program. |
| 64 | * Using Debugger:: What the debugger does; what you see while in it. |
| 65 | * Debugger Commands:: Commands used while in the debugger. |
| 66 | * Invoking the Debugger:: How to call the function @code{debug}. |
| 67 | * Internals of Debugger:: Subroutines of the debugger, and global variables. |
| 68 | @end menu |
| 69 | |
| 70 | @node Error Debugging |
| 71 | @subsection Entering the Debugger on an Error |
| 72 | @cindex error debugging |
| 73 | @cindex debugging errors |
| 74 | |
| 75 | The most important time to enter the debugger is when a Lisp error |
| 76 | happens. This allows you to investigate the immediate causes of the |
| 77 | error. |
| 78 | |
| 79 | However, entry to the debugger is not a normal consequence of an |
| 80 | error. Many commands frequently cause Lisp errors when invoked |
| 81 | inappropriately (such as @kbd{C-f} at the end of the buffer), and during |
| 82 | ordinary editing it would be very inconvenient to enter the debugger |
| 83 | each time this happens. So if you want errors to enter the debugger, set |
| 84 | the variable @code{debug-on-error} to non-@code{nil}. (The command |
| 85 | @code{toggle-debug-on-error} provides an easy way to do this.) |
| 86 | |
| 87 | @defopt debug-on-error |
| 88 | This variable determines whether the debugger is called when an error is |
| 89 | signaled and not handled. If @code{debug-on-error} is @code{t}, all |
| 90 | kinds of errors call the debugger (except those listed in |
| 91 | @code{debug-ignored-errors}). If it is @code{nil}, none call the |
| 92 | debugger. |
| 93 | |
| 94 | The value can also be a list of error conditions that should call the |
| 95 | debugger. For example, if you set it to the list |
| 96 | @code{(void-variable)}, then only errors about a variable that has no |
| 97 | value invoke the debugger. |
| 98 | |
| 99 | When this variable is non-@code{nil}, Emacs does not create an error |
| 100 | handler around process filter functions and sentinels. Therefore, |
| 101 | errors in these functions also invoke the debugger. @xref{Processes}. |
| 102 | @end defopt |
| 103 | |
| 104 | @defopt debug-ignored-errors |
| 105 | This variable specifies certain kinds of errors that should not enter |
| 106 | the debugger. Its value is a list of error condition symbols and/or |
| 107 | regular expressions. If the error has any of those condition symbols, |
| 108 | or if the error message matches any of the regular expressions, then |
| 109 | that error does not enter the debugger, regardless of the value of |
| 110 | @code{debug-on-error}. |
| 111 | |
| 112 | The normal value of this variable lists several errors that happen often |
| 113 | during editing but rarely result from bugs in Lisp programs. However, |
| 114 | ``rarely'' is not ``never''; if your program fails with an error that |
| 115 | matches this list, you will need to change this list in order to debug |
| 116 | the error. The easiest way is usually to set |
| 117 | @code{debug-ignored-errors} to @code{nil}. |
| 118 | @end defopt |
| 119 | |
| 120 | @defopt eval-expression-debug-on-error |
| 121 | If this variable has a non-@code{nil} value, then |
| 122 | @code{debug-on-error} is set to @code{t} when evaluating with the |
| 123 | command @code{eval-expression}. If |
| 124 | @code{eval-expression-debug-on-error} is @code{nil}, then the value of |
| 125 | @code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating |
| 126 | Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. |
| 127 | @end defopt |
| 128 | |
| 129 | @defopt debug-on-signal |
| 130 | Normally, errors that are caught by @code{condition-case} never run the |
| 131 | debugger, even if @code{debug-on-error} is non-@code{nil}. In other |
| 132 | words, @code{condition-case} gets a chance to handle the error before |
| 133 | the debugger gets a chance. |
| 134 | |
| 135 | If you set @code{debug-on-signal} to a non-@code{nil} value, then the |
| 136 | debugger gets the first chance at every error; an error will invoke the |
| 137 | debugger regardless of any @code{condition-case}, if it fits the |
| 138 | criteria specified by the values of @code{debug-on-error} and |
| 139 | @code{debug-ignored-errors}. |
| 140 | |
| 141 | @strong{Warning:} This variable is strong medicine! Various parts of |
| 142 | Emacs handle errors in the normal course of affairs, and you may not |
| 143 | even realize that errors happen there. If you set |
| 144 | @code{debug-on-signal} to a non-@code{nil} value, those errors will |
| 145 | enter the debugger. |
| 146 | |
| 147 | @strong{Warning:} @code{debug-on-signal} has no effect when |
| 148 | @code{debug-on-error} is @code{nil}. |
| 149 | @end defopt |
| 150 | |
| 151 | To debug an error that happens during loading of the init |
| 152 | file, use the option @samp{--debug-init}. This binds |
| 153 | @code{debug-on-error} to @code{t} while loading the init file, and |
| 154 | bypasses the @code{condition-case} which normally catches errors in the |
| 155 | init file. |
| 156 | |
| 157 | If your init file sets @code{debug-on-error}, the effect may |
| 158 | not last past the end of loading the init file. (This is an undesirable |
| 159 | byproduct of the code that implements the @samp{--debug-init} command |
| 160 | line option.) The best way to make the init file set |
| 161 | @code{debug-on-error} permanently is with @code{after-init-hook}, like |
| 162 | this: |
| 163 | |
| 164 | @example |
| 165 | (add-hook 'after-init-hook |
| 166 | (lambda () (setq debug-on-error t))) |
| 167 | @end example |
| 168 | |
| 169 | @node Infinite Loops |
| 170 | @subsection Debugging Infinite Loops |
| 171 | @cindex infinite loops |
| 172 | @cindex loops, infinite |
| 173 | @cindex quitting from infinite loop |
| 174 | @cindex stopping an infinite loop |
| 175 | |
| 176 | When a program loops infinitely and fails to return, your first |
| 177 | problem is to stop the loop. On most operating systems, you can do this |
| 178 | with @kbd{C-g}, which causes a @dfn{quit}. |
| 179 | |
| 180 | Ordinary quitting gives no information about why the program was |
| 181 | looping. To get more information, you can set the variable |
| 182 | @code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not |
| 183 | considered an error, and @code{debug-on-error} has no effect on the |
| 184 | handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on |
| 185 | errors. |
| 186 | |
| 187 | Once you have the debugger running in the middle of the infinite loop, |
| 188 | you can proceed from the debugger using the stepping commands. If you |
| 189 | step through the entire loop, you will probably get enough information |
| 190 | to solve the problem. |
| 191 | |
| 192 | @defopt debug-on-quit |
| 193 | This variable determines whether the debugger is called when @code{quit} |
| 194 | is signaled and not handled. If @code{debug-on-quit} is non-@code{nil}, |
| 195 | then the debugger is called whenever you quit (that is, type @kbd{C-g}). |
| 196 | If @code{debug-on-quit} is @code{nil}, then the debugger is not called |
| 197 | when you quit. @xref{Quitting}. |
| 198 | @end defopt |
| 199 | |
| 200 | @node Function Debugging |
| 201 | @subsection Entering the Debugger on a Function Call |
| 202 | @cindex function call debugging |
| 203 | @cindex debugging specific functions |
| 204 | |
| 205 | To investigate a problem that happens in the middle of a program, one |
| 206 | useful technique is to enter the debugger whenever a certain function is |
| 207 | called. You can do this to the function in which the problem occurs, |
| 208 | and then step through the function, or you can do this to a function |
| 209 | called shortly before the problem, step quickly over the call to that |
| 210 | function, and then step through its caller. |
| 211 | |
| 212 | @deffn Command debug-on-entry function-name |
| 213 | This function requests @var{function-name} to invoke the debugger each |
| 214 | time it is called. It works by inserting the form |
| 215 | @code{(implement-debug-on-entry)} into the function definition as the |
| 216 | first form. |
| 217 | |
| 218 | Any function or macro defined as Lisp code may be set to break on |
| 219 | entry, regardless of whether it is interpreted code or compiled code. |
| 220 | If the function is a command, it will enter the debugger when called |
| 221 | from Lisp and when called interactively (after the reading of the |
| 222 | arguments). You can also set debug-on-entry for primitive functions |
| 223 | (i.e., those written in C) this way, but it only takes effect when the |
| 224 | primitive is called from Lisp code. Debug-on-entry is not allowed for |
| 225 | special forms. |
| 226 | |
| 227 | When @code{debug-on-entry} is called interactively, it prompts for |
| 228 | @var{function-name} in the minibuffer. If the function is already set |
| 229 | up to invoke the debugger on entry, @code{debug-on-entry} does nothing. |
| 230 | @code{debug-on-entry} always returns @var{function-name}. |
| 231 | |
| 232 | @strong{Warning:} if you redefine a function after using |
| 233 | @code{debug-on-entry} on it, the code to enter the debugger is |
| 234 | discarded by the redefinition. In effect, redefining the function |
| 235 | cancels the break-on-entry feature for that function. |
| 236 | |
| 237 | Here's an example to illustrate use of this function: |
| 238 | |
| 239 | @example |
| 240 | @group |
| 241 | (defun fact (n) |
| 242 | (if (zerop n) 1 |
| 243 | (* n (fact (1- n))))) |
| 244 | @result{} fact |
| 245 | @end group |
| 246 | @group |
| 247 | (debug-on-entry 'fact) |
| 248 | @result{} fact |
| 249 | @end group |
| 250 | @group |
| 251 | (fact 3) |
| 252 | @end group |
| 253 | |
| 254 | @group |
| 255 | ------ Buffer: *Backtrace* ------ |
| 256 | Debugger entered--entering a function: |
| 257 | * fact(3) |
| 258 | eval((fact 3)) |
| 259 | eval-last-sexp-1(nil) |
| 260 | eval-last-sexp(nil) |
| 261 | call-interactively(eval-last-sexp) |
| 262 | ------ Buffer: *Backtrace* ------ |
| 263 | @end group |
| 264 | |
| 265 | @group |
| 266 | (symbol-function 'fact) |
| 267 | @result{} (lambda (n) |
| 268 | (debug (quote debug)) |
| 269 | (if (zerop n) 1 (* n (fact (1- n))))) |
| 270 | @end group |
| 271 | @end example |
| 272 | @end deffn |
| 273 | |
| 274 | @deffn Command cancel-debug-on-entry &optional function-name |
| 275 | This function undoes the effect of @code{debug-on-entry} on |
| 276 | @var{function-name}. When called interactively, it prompts for |
| 277 | @var{function-name} in the minibuffer. If @var{function-name} is |
| 278 | omitted or @code{nil}, it cancels break-on-entry for all functions. |
| 279 | Calling @code{cancel-debug-on-entry} does nothing to a function which is |
| 280 | not currently set up to break on entry. |
| 281 | @end deffn |
| 282 | |
| 283 | @node Explicit Debug |
| 284 | @subsection Explicit Entry to the Debugger |
| 285 | |
| 286 | You can cause the debugger to be called at a certain point in your |
| 287 | program by writing the expression @code{(debug)} at that point. To do |
| 288 | this, visit the source file, insert the text @samp{(debug)} at the |
| 289 | proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key |
| 290 | binding). @strong{Warning:} if you do this for temporary debugging |
| 291 | purposes, be sure to undo this insertion before you save the file! |
| 292 | |
| 293 | The place where you insert @samp{(debug)} must be a place where an |
| 294 | additional form can be evaluated and its value ignored. (If the value |
| 295 | of @code{(debug)} isn't ignored, it will alter the execution of the |
| 296 | program!) The most common suitable places are inside a @code{progn} or |
| 297 | an implicit @code{progn} (@pxref{Sequencing}). |
| 298 | |
| 299 | @node Using Debugger |
| 300 | @subsection Using the Debugger |
| 301 | |
| 302 | When the debugger is entered, it displays the previously selected |
| 303 | buffer in one window and a buffer named @samp{*Backtrace*} in another |
| 304 | window. The backtrace buffer contains one line for each level of Lisp |
| 305 | function execution currently going on. At the beginning of this buffer |
| 306 | is a message describing the reason that the debugger was invoked (such |
| 307 | as the error message and associated data, if it was invoked due to an |
| 308 | error). |
| 309 | |
| 310 | The backtrace buffer is read-only and uses a special major mode, |
| 311 | Debugger mode, in which letters are defined as debugger commands. The |
| 312 | usual Emacs editing commands are available; thus, you can switch windows |
| 313 | to examine the buffer that was being edited at the time of the error, |
| 314 | switch buffers, visit files, or do any other sort of editing. However, |
| 315 | the debugger is a recursive editing level (@pxref{Recursive Editing}) |
| 316 | and it is wise to go back to the backtrace buffer and exit the debugger |
| 317 | (with the @kbd{q} command) when you are finished with it. Exiting |
| 318 | the debugger gets out of the recursive edit and kills the backtrace |
| 319 | buffer. |
| 320 | |
| 321 | @cindex current stack frame |
| 322 | The backtrace buffer shows you the functions that are executing and |
| 323 | their argument values. It also allows you to specify a stack frame by |
| 324 | moving point to the line describing that frame. (A stack frame is the |
| 325 | place where the Lisp interpreter records information about a particular |
| 326 | invocation of a function.) The frame whose line point is on is |
| 327 | considered the @dfn{current frame}. Some of the debugger commands |
| 328 | operate on the current frame. If a line starts with a star, that means |
| 329 | that exiting that frame will call the debugger again. This is useful |
| 330 | for examining the return value of a function. |
| 331 | |
| 332 | If a function name is underlined, that means the debugger knows |
| 333 | where its source code is located. You can click @kbd{Mouse-2} on that |
| 334 | name, or move to it and type @key{RET}, to visit the source code. |
| 335 | |
| 336 | The debugger itself must be run byte-compiled, since it makes |
| 337 | assumptions about how many stack frames are used for the debugger |
| 338 | itself. These assumptions are false if the debugger is running |
| 339 | interpreted. |
| 340 | |
| 341 | @node Debugger Commands |
| 342 | @subsection Debugger Commands |
| 343 | @cindex debugger command list |
| 344 | |
| 345 | The debugger buffer (in Debugger mode) provides special commands in |
| 346 | addition to the usual Emacs commands. The most important use of |
| 347 | debugger commands is for stepping through code, so that you can see |
| 348 | how control flows. The debugger can step through the control |
| 349 | structures of an interpreted function, but cannot do so in a |
| 350 | byte-compiled function. If you would like to step through a |
| 351 | byte-compiled function, replace it with an interpreted definition of |
| 352 | the same function. (To do this, visit the source for the function and |
| 353 | type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger |
| 354 | to step through a primitive function. |
| 355 | |
| 356 | Here is a list of Debugger mode commands: |
| 357 | |
| 358 | @table @kbd |
| 359 | @item c |
| 360 | Exit the debugger and continue execution. When continuing is possible, |
| 361 | it resumes execution of the program as if the debugger had never been |
| 362 | entered (aside from any side-effects that you caused by changing |
| 363 | variable values or data structures while inside the debugger). |
| 364 | |
| 365 | Continuing is possible after entry to the debugger due to function entry |
| 366 | or exit, explicit invocation, or quitting. You cannot continue if the |
| 367 | debugger was entered because of an error. |
| 368 | |
| 369 | @item d |
| 370 | Continue execution, but enter the debugger the next time any Lisp |
| 371 | function is called. This allows you to step through the |
| 372 | subexpressions of an expression, seeing what values the subexpressions |
| 373 | compute, and what else they do. |
| 374 | |
| 375 | The stack frame made for the function call which enters the debugger in |
| 376 | this way will be flagged automatically so that the debugger will be |
| 377 | called again when the frame is exited. You can use the @kbd{u} command |
| 378 | to cancel this flag. |
| 379 | |
| 380 | @item b |
| 381 | Flag the current frame so that the debugger will be entered when the |
| 382 | frame is exited. Frames flagged in this way are marked with stars |
| 383 | in the backtrace buffer. |
| 384 | |
| 385 | @item u |
| 386 | Don't enter the debugger when the current frame is exited. This |
| 387 | cancels a @kbd{b} command on that frame. The visible effect is to |
| 388 | remove the star from the line in the backtrace buffer. |
| 389 | |
| 390 | @item j |
| 391 | Flag the current frame like @kbd{b}. Then continue execution like |
| 392 | @kbd{c}, but temporarily disable break-on-entry for all functions that |
| 393 | are set up to do so by @code{debug-on-entry}. |
| 394 | |
| 395 | @item e |
| 396 | Read a Lisp expression in the minibuffer, evaluate it, and print the |
| 397 | value in the echo area. The debugger alters certain important |
| 398 | variables, and the current buffer, as part of its operation; @kbd{e} |
| 399 | temporarily restores their values from outside the debugger, so you can |
| 400 | examine and change them. This makes the debugger more transparent. By |
| 401 | contrast, @kbd{M-:} does nothing special in the debugger; it shows you |
| 402 | the variable values within the debugger. |
| 403 | |
| 404 | @item R |
| 405 | Like @kbd{e}, but also save the result of evaluation in the |
| 406 | buffer @samp{*Debugger-record*}. |
| 407 | |
| 408 | @item q |
| 409 | Terminate the program being debugged; return to top-level Emacs |
| 410 | command execution. |
| 411 | |
| 412 | If the debugger was entered due to a @kbd{C-g} but you really want |
| 413 | to quit, and not debug, use the @kbd{q} command. |
| 414 | |
| 415 | @item r |
| 416 | Return a value from the debugger. The value is computed by reading an |
| 417 | expression with the minibuffer and evaluating it. |
| 418 | |
| 419 | The @kbd{r} command is useful when the debugger was invoked due to exit |
| 420 | from a Lisp call frame (as requested with @kbd{b} or by entering the |
| 421 | frame with @kbd{d}); then the value specified in the @kbd{r} command is |
| 422 | used as the value of that frame. It is also useful if you call |
| 423 | @code{debug} and use its return value. Otherwise, @kbd{r} has the same |
| 424 | effect as @kbd{c}, and the specified return value does not matter. |
| 425 | |
| 426 | You can't use @kbd{r} when the debugger was entered due to an error. |
| 427 | |
| 428 | @item l |
| 429 | Display a list of functions that will invoke the debugger when called. |
| 430 | This is a list of functions that are set to break on entry by means of |
| 431 | @code{debug-on-entry}. @strong{Warning:} if you redefine such a |
| 432 | function and thus cancel the effect of @code{debug-on-entry}, it may |
| 433 | erroneously show up in this list. |
| 434 | @end table |
| 435 | |
| 436 | @node Invoking the Debugger |
| 437 | @subsection Invoking the Debugger |
| 438 | |
| 439 | Here we describe in full detail the function @code{debug} that is used |
| 440 | to invoke the debugger. |
| 441 | |
| 442 | @defun debug &rest debugger-args |
| 443 | This function enters the debugger. It switches buffers to a buffer |
| 444 | named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second |
| 445 | recursive entry to the debugger, etc.), and fills it with information |
| 446 | about the stack of Lisp function calls. It then enters a recursive |
| 447 | edit, showing the backtrace buffer in Debugger mode. |
| 448 | |
| 449 | The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit |
| 450 | the recursive edit; then @code{debug} switches back to the previous |
| 451 | buffer and returns to whatever called @code{debug}. This is the only |
| 452 | way the function @code{debug} can return to its caller. |
| 453 | |
| 454 | The use of the @var{debugger-args} is that @code{debug} displays the |
| 455 | rest of its arguments at the top of the @samp{*Backtrace*} buffer, so |
| 456 | that the user can see them. Except as described below, this is the |
| 457 | @emph{only} way these arguments are used. |
| 458 | |
| 459 | However, certain values for first argument to @code{debug} have a |
| 460 | special significance. (Normally, these values are used only by the |
| 461 | internals of Emacs, and not by programmers calling @code{debug}.) Here |
| 462 | is a table of these special values: |
| 463 | |
| 464 | @table @code |
| 465 | @item lambda |
| 466 | @cindex @code{lambda} in debug |
| 467 | A first argument of @code{lambda} means @code{debug} was called |
| 468 | because of entry to a function when @code{debug-on-next-call} was |
| 469 | non-@code{nil}. The debugger displays @samp{Debugger |
| 470 | entered--entering a function:} as a line of text at the top of the |
| 471 | buffer. |
| 472 | |
| 473 | @item debug |
| 474 | @code{debug} as first argument means @code{debug} was called because |
| 475 | of entry to a function that was set to debug on entry. The debugger |
| 476 | displays the string @samp{Debugger entered--entering a function:}, |
| 477 | just as in the @code{lambda} case. It also marks the stack frame for |
| 478 | that function so that it will invoke the debugger when exited. |
| 479 | |
| 480 | @item t |
| 481 | When the first argument is @code{t}, this indicates a call to |
| 482 | @code{debug} due to evaluation of a function call form when |
| 483 | @code{debug-on-next-call} is non-@code{nil}. The debugger displays |
| 484 | @samp{Debugger entered--beginning evaluation of function call form:} |
| 485 | as the top line in the buffer. |
| 486 | |
| 487 | @item exit |
| 488 | When the first argument is @code{exit}, it indicates the exit of a |
| 489 | stack frame previously marked to invoke the debugger on exit. The |
| 490 | second argument given to @code{debug} in this case is the value being |
| 491 | returned from the frame. The debugger displays @samp{Debugger |
| 492 | entered--returning value:} in the top line of the buffer, followed by |
| 493 | the value being returned. |
| 494 | |
| 495 | @item error |
| 496 | @cindex @code{error} in debug |
| 497 | When the first argument is @code{error}, the debugger indicates that |
| 498 | it is being entered because an error or @code{quit} was signaled and |
| 499 | not handled, by displaying @samp{Debugger entered--Lisp error:} |
| 500 | followed by the error signaled and any arguments to @code{signal}. |
| 501 | For example, |
| 502 | |
| 503 | @example |
| 504 | @group |
| 505 | (let ((debug-on-error t)) |
| 506 | (/ 1 0)) |
| 507 | @end group |
| 508 | |
| 509 | @group |
| 510 | ------ Buffer: *Backtrace* ------ |
| 511 | Debugger entered--Lisp error: (arith-error) |
| 512 | /(1 0) |
| 513 | ... |
| 514 | ------ Buffer: *Backtrace* ------ |
| 515 | @end group |
| 516 | @end example |
| 517 | |
| 518 | If an error was signaled, presumably the variable |
| 519 | @code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, |
| 520 | then presumably the variable @code{debug-on-quit} is non-@code{nil}. |
| 521 | |
| 522 | @item nil |
| 523 | Use @code{nil} as the first of the @var{debugger-args} when you want |
| 524 | to enter the debugger explicitly. The rest of the @var{debugger-args} |
| 525 | are printed on the top line of the buffer. You can use this feature to |
| 526 | display messages---for example, to remind yourself of the conditions |
| 527 | under which @code{debug} is called. |
| 528 | @end table |
| 529 | @end defun |
| 530 | |
| 531 | @node Internals of Debugger |
| 532 | @subsection Internals of the Debugger |
| 533 | |
| 534 | This section describes functions and variables used internally by the |
| 535 | debugger. |
| 536 | |
| 537 | @defvar debugger |
| 538 | The value of this variable is the function to call to invoke the |
| 539 | debugger. Its value must be a function of any number of arguments, or, |
| 540 | more typically, the name of a function. This function should invoke |
| 541 | some kind of debugger. The default value of the variable is |
| 542 | @code{debug}. |
| 543 | |
| 544 | The first argument that Lisp hands to the function indicates why it |
| 545 | was called. The convention for arguments is detailed in the description |
| 546 | of @code{debug} (@pxref{Invoking the Debugger}). |
| 547 | @end defvar |
| 548 | |
| 549 | @deffn Command backtrace |
| 550 | @cindex run time stack |
| 551 | @cindex call stack |
| 552 | This function prints a trace of Lisp function calls currently active. |
| 553 | This is the function used by @code{debug} to fill up the |
| 554 | @samp{*Backtrace*} buffer. It is written in C, since it must have access |
| 555 | to the stack to determine which function calls are active. The return |
| 556 | value is always @code{nil}. |
| 557 | |
| 558 | In the following example, a Lisp expression calls @code{backtrace} |
| 559 | explicitly. This prints the backtrace to the stream |
| 560 | @code{standard-output}, which, in this case, is the buffer |
| 561 | @samp{backtrace-output}. |
| 562 | |
| 563 | Each line of the backtrace represents one function call. The line shows |
| 564 | the values of the function's arguments if they are all known; if they |
| 565 | are still being computed, the line says so. The arguments of special |
| 566 | forms are elided. |
| 567 | |
| 568 | @smallexample |
| 569 | @group |
| 570 | (with-output-to-temp-buffer "backtrace-output" |
| 571 | (let ((var 1)) |
| 572 | (save-excursion |
| 573 | (setq var (eval '(progn |
| 574 | (1+ var) |
| 575 | (list 'testing (backtrace)))))))) |
| 576 | |
| 577 | @result{} (testing nil) |
| 578 | @end group |
| 579 | |
| 580 | @group |
| 581 | ----------- Buffer: backtrace-output ------------ |
| 582 | backtrace() |
| 583 | (list ...computing arguments...) |
| 584 | @end group |
| 585 | (progn ...) |
| 586 | eval((progn (1+ var) (list (quote testing) (backtrace)))) |
| 587 | (setq ...) |
| 588 | (save-excursion ...) |
| 589 | (let ...) |
| 590 | (with-output-to-temp-buffer ...) |
| 591 | eval((with-output-to-temp-buffer ...)) |
| 592 | eval-last-sexp-1(nil) |
| 593 | @group |
| 594 | eval-last-sexp(nil) |
| 595 | call-interactively(eval-last-sexp) |
| 596 | ----------- Buffer: backtrace-output ------------ |
| 597 | @end group |
| 598 | @end smallexample |
| 599 | @end deffn |
| 600 | |
| 601 | @ignore @c Not worth mentioning |
| 602 | @defopt stack-trace-on-error |
| 603 | @cindex stack trace |
| 604 | This variable controls whether Lisp automatically displays a |
| 605 | backtrace buffer after every error that is not handled. A quit signal |
| 606 | counts as an error for this variable. If it is non-@code{nil} then a |
| 607 | backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every |
| 608 | error. If it is @code{nil}, then a backtrace is not shown. |
| 609 | |
| 610 | When a backtrace is shown, that buffer is not selected. If either |
| 611 | @code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then |
| 612 | a backtrace is shown in one buffer, and the debugger is popped up in |
| 613 | another buffer with its own backtrace. |
| 614 | |
| 615 | We consider this feature to be obsolete and superseded by the debugger |
| 616 | itself. |
| 617 | @end defopt |
| 618 | @end ignore |
| 619 | |
| 620 | @defvar debug-on-next-call |
| 621 | @cindex @code{eval}, and debugging |
| 622 | @cindex @code{apply}, and debugging |
| 623 | @cindex @code{funcall}, and debugging |
| 624 | If this variable is non-@code{nil}, it says to call the debugger before |
| 625 | the next @code{eval}, @code{apply} or @code{funcall}. Entering the |
| 626 | debugger sets @code{debug-on-next-call} to @code{nil}. |
| 627 | |
| 628 | The @kbd{d} command in the debugger works by setting this variable. |
| 629 | @end defvar |
| 630 | |
| 631 | @defun backtrace-debug level flag |
| 632 | This function sets the debug-on-exit flag of the stack frame @var{level} |
| 633 | levels down the stack, giving it the value @var{flag}. If @var{flag} is |
| 634 | non-@code{nil}, this will cause the debugger to be entered when that |
| 635 | frame later exits. Even a nonlocal exit through that frame will enter |
| 636 | the debugger. |
| 637 | |
| 638 | This function is used only by the debugger. |
| 639 | @end defun |
| 640 | |
| 641 | @defvar command-debug-status |
| 642 | This variable records the debugging status of the current interactive |
| 643 | command. Each time a command is called interactively, this variable is |
| 644 | bound to @code{nil}. The debugger can set this variable to leave |
| 645 | information for future debugger invocations during the same command |
| 646 | invocation. |
| 647 | |
| 648 | The advantage of using this variable rather than an ordinary global |
| 649 | variable is that the data will never carry over to a subsequent command |
| 650 | invocation. |
| 651 | @end defvar |
| 652 | |
| 653 | @defun backtrace-frame frame-number |
| 654 | The function @code{backtrace-frame} is intended for use in Lisp |
| 655 | debuggers. It returns information about what computation is happening |
| 656 | in the stack frame @var{frame-number} levels down. |
| 657 | |
| 658 | If that frame has not evaluated the arguments yet, or is a special |
| 659 | form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. |
| 660 | |
| 661 | If that frame has evaluated its arguments and called its function |
| 662 | already, the return value is @code{(t @var{function} |
| 663 | @var{arg-values}@dots{})}. |
| 664 | |
| 665 | In the return value, @var{function} is whatever was supplied as the |
| 666 | @sc{car} of the evaluated list, or a @code{lambda} expression in the |
| 667 | case of a macro call. If the function has a @code{&rest} argument, that |
| 668 | is represented as the tail of the list @var{arg-values}. |
| 669 | |
| 670 | If @var{frame-number} is out of range, @code{backtrace-frame} returns |
| 671 | @code{nil}. |
| 672 | @end defun |
| 673 | |
| 674 | @include edebug.texi |
| 675 | |
| 676 | @node Syntax Errors |
| 677 | @section Debugging Invalid Lisp Syntax |
| 678 | |
| 679 | The Lisp reader reports invalid syntax, but cannot say where the real |
| 680 | problem is. For example, the error ``End of file during parsing'' in |
| 681 | evaluating an expression indicates an excess of open parentheses (or |
| 682 | square brackets). The reader detects this imbalance at the end of the |
| 683 | file, but it cannot figure out where the close parenthesis should have |
| 684 | been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close |
| 685 | parenthesis or missing open parenthesis, but does not say where the |
| 686 | missing parenthesis belongs. How, then, to find what to change? |
| 687 | |
| 688 | If the problem is not simply an imbalance of parentheses, a useful |
| 689 | technique is to try @kbd{C-M-e} at the beginning of each defun, and see |
| 690 | if it goes to the place where that defun appears to end. If it does |
| 691 | not, there is a problem in that defun. |
| 692 | |
| 693 | However, unmatched parentheses are the most common syntax errors in |
| 694 | Lisp, and we can give further advice for those cases. (In addition, |
| 695 | just moving point through the code with Show Paren mode enabled might |
| 696 | find the mismatch.) |
| 697 | |
| 698 | @menu |
| 699 | * Excess Open:: How to find a spurious open paren or missing close. |
| 700 | * Excess Close:: How to find a spurious close paren or missing open. |
| 701 | @end menu |
| 702 | |
| 703 | @node Excess Open |
| 704 | @subsection Excess Open Parentheses |
| 705 | |
| 706 | The first step is to find the defun that is unbalanced. If there is |
| 707 | an excess open parenthesis, the way to do this is to go to the end of |
| 708 | the file and type @kbd{C-u C-M-u}. This will move you to the |
| 709 | beginning of the first defun that is unbalanced. |
| 710 | |
| 711 | The next step is to determine precisely what is wrong. There is no |
| 712 | way to be sure of this except by studying the program, but often the |
| 713 | existing indentation is a clue to where the parentheses should have |
| 714 | been. The easiest way to use this clue is to reindent with @kbd{C-M-q} |
| 715 | and see what moves. @strong{But don't do this yet!} Keep reading, |
| 716 | first. |
| 717 | |
| 718 | Before you do this, make sure the defun has enough close parentheses. |
| 719 | Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest |
| 720 | of the file until the end. So move to the end of the defun and insert a |
| 721 | close parenthesis there. Don't use @kbd{C-M-e} to move there, since |
| 722 | that too will fail to work until the defun is balanced. |
| 723 | |
| 724 | Now you can go to the beginning of the defun and type @kbd{C-M-q}. |
| 725 | Usually all the lines from a certain point to the end of the function |
| 726 | will shift to the right. There is probably a missing close parenthesis, |
| 727 | or a superfluous open parenthesis, near that point. (However, don't |
| 728 | assume this is true; study the code to make sure.) Once you have found |
| 729 | the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old |
| 730 | indentation is probably appropriate to the intended parentheses. |
| 731 | |
| 732 | After you think you have fixed the problem, use @kbd{C-M-q} again. If |
| 733 | the old indentation actually fit the intended nesting of parentheses, |
| 734 | and you have put back those parentheses, @kbd{C-M-q} should not change |
| 735 | anything. |
| 736 | |
| 737 | @node Excess Close |
| 738 | @subsection Excess Close Parentheses |
| 739 | |
| 740 | To deal with an excess close parenthesis, first go to the beginning |
| 741 | of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first |
| 742 | unbalanced defun. |
| 743 | |
| 744 | Then find the actual matching close parenthesis by typing @kbd{C-M-f} |
| 745 | at the beginning of that defun. This will leave you somewhere short of |
| 746 | the place where the defun ought to end. It is possible that you will |
| 747 | find a spurious close parenthesis in that vicinity. |
| 748 | |
| 749 | If you don't see a problem at that point, the next thing to do is to |
| 750 | type @kbd{C-M-q} at the beginning of the defun. A range of lines will |
| 751 | probably shift left; if so, the missing open parenthesis or spurious |
| 752 | close parenthesis is probably near the first of those lines. (However, |
| 753 | don't assume this is true; study the code to make sure.) Once you have |
| 754 | found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the |
| 755 | old indentation is probably appropriate to the intended parentheses. |
| 756 | |
| 757 | After you think you have fixed the problem, use @kbd{C-M-q} again. If |
| 758 | the old indentation actually fits the intended nesting of parentheses, |
| 759 | and you have put back those parentheses, @kbd{C-M-q} should not change |
| 760 | anything. |
| 761 | |
| 762 | @node Test Coverage |
| 763 | @section Test Coverage |
| 764 | @cindex coverage testing |
| 765 | |
| 766 | @findex testcover-start |
| 767 | @findex testcover-mark-all |
| 768 | @findex testcover-next-mark |
| 769 | You can do coverage testing for a file of Lisp code by loading the |
| 770 | @code{testcover} library and using the command @kbd{M-x |
| 771 | testcover-start @key{RET} @var{file} @key{RET}} to instrument the |
| 772 | code. Then test your code by calling it one or more times. Then use |
| 773 | the command @kbd{M-x testcover-mark-all} to display colored highlights |
| 774 | on the code to show where coverage is insufficient. The command |
| 775 | @kbd{M-x testcover-next-mark} will move point forward to the next |
| 776 | highlighted spot. |
| 777 | |
| 778 | Normally, a red highlight indicates the form was never completely |
| 779 | evaluated; a brown highlight means it always evaluated to the same |
| 780 | value (meaning there has been little testing of what is done with the |
| 781 | result). However, the red highlight is skipped for forms that can't |
| 782 | possibly complete their evaluation, such as @code{error}. The brown |
| 783 | highlight is skipped for forms that are expected to always evaluate to |
| 784 | the same value, such as @code{(setq x 14)}. |
| 785 | |
| 786 | For difficult cases, you can add do-nothing macros to your code to |
| 787 | give advice to the test coverage tool. |
| 788 | |
| 789 | @defmac 1value form |
| 790 | Evaluate @var{form} and return its value, but inform coverage testing |
| 791 | that @var{form}'s value should always be the same. |
| 792 | @end defmac |
| 793 | |
| 794 | @defmac noreturn form |
| 795 | Evaluate @var{form}, informing coverage testing that @var{form} should |
| 796 | never return. If it ever does return, you get a run-time error. |
| 797 | @end defmac |
| 798 | |
| 799 | @node Compilation Errors |
| 800 | @section Debugging Problems in Compilation |
| 801 | |
| 802 | When an error happens during byte compilation, it is normally due to |
| 803 | invalid syntax in the program you are compiling. The compiler prints a |
| 804 | suitable error message in the @samp{*Compile-Log*} buffer, and then |
| 805 | stops. The message may state a function name in which the error was |
| 806 | found, or it may not. Either way, here is how to find out where in the |
| 807 | file the error occurred. |
| 808 | |
| 809 | What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}. |
| 810 | (Note that the buffer name starts with a space, so it does not show |
| 811 | up in @kbd{M-x list-buffers}.) This buffer contains the program being |
| 812 | compiled, and point shows how far the byte compiler was able to read. |
| 813 | |
| 814 | If the error was due to invalid Lisp syntax, point shows exactly where |
| 815 | the invalid syntax was @emph{detected}. The cause of the error is not |
| 816 | necessarily near by! Use the techniques in the previous section to find |
| 817 | the error. |
| 818 | |
| 819 | If the error was detected while compiling a form that had been read |
| 820 | successfully, then point is located at the end of the form. In this |
| 821 | case, this technique can't localize the error precisely, but can still |
| 822 | show you which function to check. |
| 823 | |
| 824 | @ignore |
| 825 | arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7 |
| 826 | @end ignore |