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