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