Mercurial > hg > xemacs-beta
annotate man/lispref/debugging.texi @ 5917:ffb5abc8dc4e
Fix a bug in the #'equalp compiler macro.
lisp/ChangeLog addition:
2015-06-11 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (equalp):
Fix a bug in this compiler macro when passed constants in a
certain order.
tests/ChangeLog addition:
2015-06-11 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Add a test looking for a bug just fixed in the equalp compiler
macro.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 11 Jun 2015 16:09:11 +0100 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
42 @node Debugger, Syntax Errors, Debugging, Debugging |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
67 @node Error Debugging, Infinite Loops, Debugger, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
133 @node Infinite Loops, Function Debugging, Error Debugging, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
164 @node Function Debugging, Explicit Debug, Infinite Loops, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
246 @node Explicit Debug, Using Debugger, Function Debugging, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
261 @node Using Debugger, Debugger Commands, Explicit Debug, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
299 @node Debugger Commands, Invoking the Debugger, Using Debugger, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
394 @node Invoking the Debugger, Internals of Debugger, Debugger Commands, Debugger |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
493 @node Internals of Debugger, , Invoking the Debugger, Debugger |
| 428 | 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. | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
532 The arguments of special operators are elided. |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
640 @node Syntax Errors, Compilation Errors, Debugger, Debugging |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
665 @node Excess Open, Excess Close, Syntax Errors, Syntax Errors |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
4905
diff
changeset
|
701 @node Excess Close, , Excess Open, Syntax Errors |
| 428 | 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 |