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