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