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,
4 @c 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/debugging
7 @node Debugging, Read and Print, Advising Functions, Top
8 @chapter Debugging Lisp Programs
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.
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.
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.
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.
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.
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}.
42 For debugging problems in terminal descriptions, the
43 @code{open-termscript} function can be useful. @xref{Terminal Output}.
46 @section The Lisp Debugger
47 @cindex debugger for Emacs Lisp
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}.
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.
71 @subsection Entering the Debugger on an Error
72 @cindex error debugging
73 @cindex debugging errors
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
79 However, entry to the debugger is not a normal consequence of an
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.)
87 @defopt debug-on-error
88 This variable determines whether the debugger is called when an error is
89 signaled and not handled. If @code{debug-on-error} is @code{t}, all
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. (Note that @code{eval-expression-debug-on-error} affects the
93 setting of this variable in some cases; see below.)
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.
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}.
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}.
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}.
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}.
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.
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}.
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
148 @strong{Warning:} @code{debug-on-signal} has no effect when
149 @code{debug-on-error} is @code{nil}.
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
158 If your init file sets @code{debug-on-error}, the effect may
159 not last past the end of loading the init file. (This is an undesirable
160 byproduct of the code that implements the @samp{--debug-init} command
161 line option.) The best way to make the init file set
162 @code{debug-on-error} permanently is with @code{after-init-hook}, like
166 (add-hook 'after-init-hook
167 (lambda () (setq debug-on-error t)))
171 @subsection Debugging Infinite Loops
172 @cindex infinite loops
173 @cindex loops, infinite
174 @cindex quitting from infinite loop
175 @cindex stopping an infinite loop
177 When a program loops infinitely and fails to return, your first
178 problem is to stop the loop. On most operating systems, you can do this
179 with @kbd{C-g}, which causes a @dfn{quit}.
181 Ordinary quitting gives no information about why the program was
182 looping. To get more information, you can set the variable
183 @code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
184 considered an error, and @code{debug-on-error} has no effect on the
185 handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on
188 Once you have the debugger running in the middle of the infinite loop,
189 you can proceed from the debugger using the stepping commands. If you
190 step through the entire loop, you will probably get enough information
191 to solve the problem.
193 @defopt debug-on-quit
194 This variable determines whether the debugger is called when @code{quit}
195 is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
196 then the debugger is called whenever you quit (that is, type @kbd{C-g}).
197 If @code{debug-on-quit} is @code{nil}, then the debugger is not called
198 when you quit. @xref{Quitting}.
201 @node Function Debugging
202 @subsection Entering the Debugger on a Function Call
203 @cindex function call debugging
204 @cindex debugging specific functions
206 To investigate a problem that happens in the middle of a program, one
207 useful technique is to enter the debugger whenever a certain function is
208 called. You can do this to the function in which the problem occurs,
209 and then step through the function, or you can do this to a function
210 called shortly before the problem, step quickly over the call to that
211 function, and then step through its caller.
213 @deffn Command debug-on-entry function-name
214 This function requests @var{function-name} to invoke the debugger each
215 time it is called. It works by inserting the form
216 @code{(implement-debug-on-entry)} into the function definition as the
219 Any function or macro defined as Lisp code may be set to break on
220 entry, regardless of whether it is interpreted code or compiled code.
221 If the function is a command, it will enter the debugger when called
222 from Lisp and when called interactively (after the reading of the
223 arguments). You can also set debug-on-entry for primitive functions
224 (i.e., those written in C) this way, but it only takes effect when the
225 primitive is called from Lisp code. Debug-on-entry is not allowed for
228 When @code{debug-on-entry} is called interactively, it prompts for
229 @var{function-name} in the minibuffer. If the function is already set
230 up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
231 @code{debug-on-entry} always returns @var{function-name}.
233 @strong{Warning:} if you redefine a function after using
234 @code{debug-on-entry} on it, the code to enter the debugger is
235 discarded by the redefinition. In effect, redefining the function
236 cancels the break-on-entry feature for that function.
238 Here's an example to illustrate use of this function:
244 (* n (fact (1- n)))))
248 (debug-on-entry 'fact)
256 ------ Buffer: *Backtrace* ------
257 Debugger entered--entering a function:
260 eval-last-sexp-1(nil)
262 call-interactively(eval-last-sexp)
263 ------ Buffer: *Backtrace* ------
267 (symbol-function 'fact)
268 @result{} (lambda (n)
269 (debug (quote debug))
270 (if (zerop n) 1 (* n (fact (1- n)))))
275 @deffn Command cancel-debug-on-entry &optional function-name
276 This function undoes the effect of @code{debug-on-entry} on
277 @var{function-name}. When called interactively, it prompts for
278 @var{function-name} in the minibuffer. If @var{function-name} is
279 omitted or @code{nil}, it cancels break-on-entry for all functions.
280 Calling @code{cancel-debug-on-entry} does nothing to a function which is
281 not currently set up to break on entry.
285 @subsection Explicit Entry to the Debugger
287 You can cause the debugger to be called at a certain point in your
288 program by writing the expression @code{(debug)} at that point. To do
289 this, visit the source file, insert the text @samp{(debug)} at the
290 proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key
291 binding). @strong{Warning:} if you do this for temporary debugging
292 purposes, be sure to undo this insertion before you save the file!
294 The place where you insert @samp{(debug)} must be a place where an
295 additional form can be evaluated and its value ignored. (If the value
296 of @code{(debug)} isn't ignored, it will alter the execution of the
297 program!) The most common suitable places are inside a @code{progn} or
298 an implicit @code{progn} (@pxref{Sequencing}).
301 @subsection Using the Debugger
303 When the debugger is entered, it displays the previously selected
304 buffer in one window and a buffer named @samp{*Backtrace*} in another
305 window. The backtrace buffer contains one line for each level of Lisp
306 function execution currently going on. At the beginning of this buffer
307 is a message describing the reason that the debugger was invoked (such
308 as the error message and associated data, if it was invoked due to an
311 The backtrace buffer is read-only and uses a special major mode,
312 Debugger mode, in which letters are defined as debugger commands. The
313 usual Emacs editing commands are available; thus, you can switch windows
314 to examine the buffer that was being edited at the time of the error,
315 switch buffers, visit files, or do any other sort of editing. However,
316 the debugger is a recursive editing level (@pxref{Recursive Editing})
317 and it is wise to go back to the backtrace buffer and exit the debugger
318 (with the @kbd{q} command) when you are finished with it. Exiting
319 the debugger gets out of the recursive edit and kills the backtrace
322 @cindex current stack frame
323 The backtrace buffer shows you the functions that are executing and
324 their argument values. It also allows you to specify a stack frame by
325 moving point to the line describing that frame. (A stack frame is the
326 place where the Lisp interpreter records information about a particular
327 invocation of a function.) The frame whose line point is on is
328 considered the @dfn{current frame}. Some of the debugger commands
329 operate on the current frame. If a line starts with a star, that means
330 that exiting that frame will call the debugger again. This is useful
331 for examining the return value of a function.
333 If a function name is underlined, that means the debugger knows
334 where its source code is located. You can click @kbd{Mouse-2} on that
335 name, or move to it and type @key{RET}, to visit the source code.
337 The debugger itself must be run byte-compiled, since it makes
338 assumptions about how many stack frames are used for the debugger
339 itself. These assumptions are false if the debugger is running
342 @node Debugger Commands
343 @subsection Debugger Commands
344 @cindex debugger command list
346 The debugger buffer (in Debugger mode) provides special commands in
347 addition to the usual Emacs commands. The most important use of
348 debugger commands is for stepping through code, so that you can see
349 how control flows. The debugger can step through the control
350 structures of an interpreted function, but cannot do so in a
351 byte-compiled function. If you would like to step through a
352 byte-compiled function, replace it with an interpreted definition of
353 the same function. (To do this, visit the source for the function and
354 type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
355 to step through a primitive function.
357 Here is a list of Debugger mode commands:
361 Exit the debugger and continue execution. When continuing is possible,
362 it resumes execution of the program as if the debugger had never been
363 entered (aside from any side-effects that you caused by changing
364 variable values or data structures while inside the debugger).
366 Continuing is possible after entry to the debugger due to function entry
367 or exit, explicit invocation, or quitting. You cannot continue if the
368 debugger was entered because of an error.
371 Continue execution, but enter the debugger the next time any Lisp
372 function is called. This allows you to step through the
373 subexpressions of an expression, seeing what values the subexpressions
374 compute, and what else they do.
376 The stack frame made for the function call which enters the debugger in
377 this way will be flagged automatically so that the debugger will be
378 called again when the frame is exited. You can use the @kbd{u} command
382 Flag the current frame so that the debugger will be entered when the
383 frame is exited. Frames flagged in this way are marked with stars
384 in the backtrace buffer.
387 Don't enter the debugger when the current frame is exited. This
388 cancels a @kbd{b} command on that frame. The visible effect is to
389 remove the star from the line in the backtrace buffer.
392 Flag the current frame like @kbd{b}. Then continue execution like
393 @kbd{c}, but temporarily disable break-on-entry for all functions that
394 are set up to do so by @code{debug-on-entry}.
397 Read a Lisp expression in the minibuffer, evaluate it, and print the
398 value in the echo area. The debugger alters certain important
399 variables, and the current buffer, as part of its operation; @kbd{e}
400 temporarily restores their values from outside the debugger, so you can
401 examine and change them. This makes the debugger more transparent. By
402 contrast, @kbd{M-:} does nothing special in the debugger; it shows you
403 the variable values within the debugger.
406 Like @kbd{e}, but also save the result of evaluation in the
407 buffer @samp{*Debugger-record*}.
410 Terminate the program being debugged; return to top-level Emacs
413 If the debugger was entered due to a @kbd{C-g} but you really want
414 to quit, and not debug, use the @kbd{q} command.
417 Return a value from the debugger. The value is computed by reading an
418 expression with the minibuffer and evaluating it.
420 The @kbd{r} command is useful when the debugger was invoked due to exit
421 from a Lisp call frame (as requested with @kbd{b} or by entering the
422 frame with @kbd{d}); then the value specified in the @kbd{r} command is
423 used as the value of that frame. It is also useful if you call
424 @code{debug} and use its return value. Otherwise, @kbd{r} has the same
425 effect as @kbd{c}, and the specified return value does not matter.
427 You can't use @kbd{r} when the debugger was entered due to an error.
430 Display a list of functions that will invoke the debugger when called.
431 This is a list of functions that are set to break on entry by means of
432 @code{debug-on-entry}. @strong{Warning:} if you redefine such a
433 function and thus cancel the effect of @code{debug-on-entry}, it may
434 erroneously show up in this list.
437 @node Invoking the Debugger
438 @subsection Invoking the Debugger
440 Here we describe in full detail the function @code{debug} that is used
441 to invoke the debugger.
443 @defun debug &rest debugger-args
444 This function enters the debugger. It switches buffers to a buffer
445 named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
446 recursive entry to the debugger, etc.), and fills it with information
447 about the stack of Lisp function calls. It then enters a recursive
448 edit, showing the backtrace buffer in Debugger mode.
450 The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
451 the recursive edit; then @code{debug} switches back to the previous
452 buffer and returns to whatever called @code{debug}. This is the only
453 way the function @code{debug} can return to its caller.
455 The use of the @var{debugger-args} is that @code{debug} displays the
456 rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
457 that the user can see them. Except as described below, this is the
458 @emph{only} way these arguments are used.
460 However, certain values for first argument to @code{debug} have a
461 special significance. (Normally, these values are used only by the
462 internals of Emacs, and not by programmers calling @code{debug}.) Here
463 is a table of these special values:
467 @cindex @code{lambda} in debug
468 A first argument of @code{lambda} means @code{debug} was called
469 because of entry to a function when @code{debug-on-next-call} was
470 non-@code{nil}. The debugger displays @samp{Debugger
471 entered--entering a function:} as a line of text at the top of the
475 @code{debug} as first argument means @code{debug} was called because
476 of entry to a function that was set to debug on entry. The debugger
477 displays the string @samp{Debugger entered--entering a function:},
478 just as in the @code{lambda} case. It also marks the stack frame for
479 that function so that it will invoke the debugger when exited.
482 When the first argument is @code{t}, this indicates a call to
483 @code{debug} due to evaluation of a function call form when
484 @code{debug-on-next-call} is non-@code{nil}. The debugger displays
485 @samp{Debugger entered--beginning evaluation of function call form:}
486 as the top line in the buffer.
489 When the first argument is @code{exit}, it indicates the exit of a
490 stack frame previously marked to invoke the debugger on exit. The
491 second argument given to @code{debug} in this case is the value being
492 returned from the frame. The debugger displays @samp{Debugger
493 entered--returning value:} in the top line of the buffer, followed by
494 the value being returned.
497 @cindex @code{error} in debug
498 When the first argument is @code{error}, the debugger indicates that
499 it is being entered because an error or @code{quit} was signaled and
500 not handled, by displaying @samp{Debugger entered--Lisp error:}
501 followed by the error signaled and any arguments to @code{signal}.
506 (let ((debug-on-error t))
511 ------ Buffer: *Backtrace* ------
512 Debugger entered--Lisp error: (arith-error)
515 ------ Buffer: *Backtrace* ------
519 If an error was signaled, presumably the variable
520 @code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled,
521 then presumably the variable @code{debug-on-quit} is non-@code{nil}.
524 Use @code{nil} as the first of the @var{debugger-args} when you want
525 to enter the debugger explicitly. The rest of the @var{debugger-args}
526 are printed on the top line of the buffer. You can use this feature to
527 display messages---for example, to remind yourself of the conditions
528 under which @code{debug} is called.
532 @node Internals of Debugger
533 @subsection Internals of the Debugger
535 This section describes functions and variables used internally by the
539 The value of this variable is the function to call to invoke the
540 debugger. Its value must be a function of any number of arguments, or,
541 more typically, the name of a function. This function should invoke
542 some kind of debugger. The default value of the variable is
545 The first argument that Lisp hands to the function indicates why it
546 was called. The convention for arguments is detailed in the description
547 of @code{debug} (@pxref{Invoking the Debugger}).
550 @deffn Command backtrace
551 @cindex run time stack
553 This function prints a trace of Lisp function calls currently active.
554 This is the function used by @code{debug} to fill up the
555 @samp{*Backtrace*} buffer. It is written in C, since it must have access
556 to the stack to determine which function calls are active. The return
557 value is always @code{nil}.
559 In the following example, a Lisp expression calls @code{backtrace}
560 explicitly. This prints the backtrace to the stream
561 @code{standard-output}, which, in this case, is the buffer
562 @samp{backtrace-output}.
564 Each line of the backtrace represents one function call. The line shows
565 the values of the function's arguments if they are all known; if they
566 are still being computed, the line says so. The arguments of special
571 (with-output-to-temp-buffer "backtrace-output"
574 (setq var (eval '(progn
576 (list 'testing (backtrace))))))))
578 @result{} (testing nil)
582 ----------- Buffer: backtrace-output ------------
584 (list ...computing arguments...)
587 eval((progn (1+ var) (list (quote testing) (backtrace))))
591 (with-output-to-temp-buffer ...)
592 eval((with-output-to-temp-buffer ...))
593 eval-last-sexp-1(nil)
596 call-interactively(eval-last-sexp)
597 ----------- Buffer: backtrace-output ------------
602 @ignore @c Not worth mentioning
603 @defopt stack-trace-on-error
605 This variable controls whether Lisp automatically displays a
606 backtrace buffer after every error that is not handled. A quit signal
607 counts as an error for this variable. If it is non-@code{nil} then a
608 backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
609 error. If it is @code{nil}, then a backtrace is not shown.
611 When a backtrace is shown, that buffer is not selected. If either
612 @code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
613 a backtrace is shown in one buffer, and the debugger is popped up in
614 another buffer with its own backtrace.
616 We consider this feature to be obsolete and superseded by the debugger
621 @defvar debug-on-next-call
622 @cindex @code{eval}, and debugging
623 @cindex @code{apply}, and debugging
624 @cindex @code{funcall}, and debugging
625 If this variable is non-@code{nil}, it says to call the debugger before
626 the next @code{eval}, @code{apply} or @code{funcall}. Entering the
627 debugger sets @code{debug-on-next-call} to @code{nil}.
629 The @kbd{d} command in the debugger works by setting this variable.
632 @defun backtrace-debug level flag
633 This function sets the debug-on-exit flag of the stack frame @var{level}
634 levels down the stack, giving it the value @var{flag}. If @var{flag} is
635 non-@code{nil}, this will cause the debugger to be entered when that
636 frame later exits. Even a nonlocal exit through that frame will enter
639 This function is used only by the debugger.
642 @defvar command-debug-status
643 This variable records the debugging status of the current interactive
644 command. Each time a command is called interactively, this variable is
645 bound to @code{nil}. The debugger can set this variable to leave
646 information for future debugger invocations during the same command
649 The advantage of using this variable rather than an ordinary global
650 variable is that the data will never carry over to a subsequent command
654 @defun backtrace-frame frame-number
655 The function @code{backtrace-frame} is intended for use in Lisp
656 debuggers. It returns information about what computation is happening
657 in the stack frame @var{frame-number} levels down.
659 If that frame has not evaluated the arguments yet, or is a special
660 form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
662 If that frame has evaluated its arguments and called its function
663 already, the return value is @code{(t @var{function}
664 @var{arg-values}@dots{})}.
666 In the return value, @var{function} is whatever was supplied as the
667 @sc{car} of the evaluated list, or a @code{lambda} expression in the
668 case of a macro call. If the function has a @code{&rest} argument, that
669 is represented as the tail of the list @var{arg-values}.
671 If @var{frame-number} is out of range, @code{backtrace-frame} returns
678 @section Debugging Invalid Lisp Syntax
679 @cindex debugging invalid Lisp syntax
681 The Lisp reader reports invalid syntax, but cannot say where the real
682 problem is. For example, the error ``End of file during parsing'' in
683 evaluating an expression indicates an excess of open parentheses (or
684 square brackets). The reader detects this imbalance at the end of the
685 file, but it cannot figure out where the close parenthesis should have
686 been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close
687 parenthesis or missing open parenthesis, but does not say where the
688 missing parenthesis belongs. How, then, to find what to change?
690 If the problem is not simply an imbalance of parentheses, a useful
691 technique is to try @kbd{C-M-e} at the beginning of each defun, and see
692 if it goes to the place where that defun appears to end. If it does
693 not, there is a problem in that defun.
695 @cindex unbalanced parentheses
696 @cindex parenthesis mismatch, debugging
697 However, unmatched parentheses are the most common syntax errors in
698 Lisp, and we can give further advice for those cases. (In addition,
699 just moving point through the code with Show Paren mode enabled might
703 * Excess Open:: How to find a spurious open paren or missing close.
704 * Excess Close:: How to find a spurious close paren or missing open.
708 @subsection Excess Open Parentheses
710 The first step is to find the defun that is unbalanced. If there is
711 an excess open parenthesis, the way to do this is to go to the end of
712 the file and type @kbd{C-u C-M-u}. This will move you to the
713 beginning of the first defun that is unbalanced.
715 The next step is to determine precisely what is wrong. There is no
716 way to be sure of this except by studying the program, but often the
717 existing indentation is a clue to where the parentheses should have
718 been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
719 and see what moves. @strong{But don't do this yet!} Keep reading,
722 Before you do this, make sure the defun has enough close parentheses.
723 Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
724 of the file until the end. So move to the end of the defun and insert a
725 close parenthesis there. Don't use @kbd{C-M-e} to move there, since
726 that too will fail to work until the defun is balanced.
728 Now you can go to the beginning of the defun and type @kbd{C-M-q}.
729 Usually all the lines from a certain point to the end of the function
730 will shift to the right. There is probably a missing close parenthesis,
731 or a superfluous open parenthesis, near that point. (However, don't
732 assume this is true; study the code to make sure.) Once you have found
733 the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
734 indentation is probably appropriate to the intended parentheses.
736 After you think you have fixed the problem, use @kbd{C-M-q} again. If
737 the old indentation actually fit the intended nesting of parentheses,
738 and you have put back those parentheses, @kbd{C-M-q} should not change
742 @subsection Excess Close Parentheses
744 To deal with an excess close parenthesis, first go to the beginning
745 of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
748 Then find the actual matching close parenthesis by typing @kbd{C-M-f}
749 at the beginning of that defun. This will leave you somewhere short of
750 the place where the defun ought to end. It is possible that you will
751 find a spurious close parenthesis in that vicinity.
753 If you don't see a problem at that point, the next thing to do is to
754 type @kbd{C-M-q} at the beginning of the defun. A range of lines will
755 probably shift left; if so, the missing open parenthesis or spurious
756 close parenthesis is probably near the first of those lines. (However,
757 don't assume this is true; study the code to make sure.) Once you have
758 found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
759 old indentation is probably appropriate to the intended parentheses.
761 After you think you have fixed the problem, use @kbd{C-M-q} again. If
762 the old indentation actually fits the intended nesting of parentheses,
763 and you have put back those parentheses, @kbd{C-M-q} should not change
767 @section Test Coverage
768 @cindex coverage testing
770 @findex testcover-start
771 @findex testcover-mark-all
772 @findex testcover-next-mark
773 You can do coverage testing for a file of Lisp code by loading the
774 @code{testcover} library and using the command @kbd{M-x
775 testcover-start @key{RET} @var{file} @key{RET}} to instrument the
776 code. Then test your code by calling it one or more times. Then use
777 the command @kbd{M-x testcover-mark-all} to display colored highlights
778 on the code to show where coverage is insufficient. The command
779 @kbd{M-x testcover-next-mark} will move point forward to the next
782 Normally, a red highlight indicates the form was never completely
783 evaluated; a brown highlight means it always evaluated to the same
784 value (meaning there has been little testing of what is done with the
785 result). However, the red highlight is skipped for forms that can't
786 possibly complete their evaluation, such as @code{error}. The brown
787 highlight is skipped for forms that are expected to always evaluate to
788 the same value, such as @code{(setq x 14)}.
790 For difficult cases, you can add do-nothing macros to your code to
791 give advice to the test coverage tool.
794 Evaluate @var{form} and return its value, but inform coverage testing
795 that @var{form}'s value should always be the same.
798 @defmac noreturn form
799 Evaluate @var{form}, informing coverage testing that @var{form} should
800 never return. If it ever does return, you get a run-time error.
803 Edebug also has a coverage testing feature (@pxref{Coverage
804 Testing}). These features partly duplicate each other, and it would
805 be cleaner to combine them.
807 @node Compilation Errors
808 @section Debugging Problems in Compilation
809 @cindex debugging byte compilation problems
811 When an error happens during byte compilation, it is normally due to
812 invalid syntax in the program you are compiling. The compiler prints a
813 suitable error message in the @samp{*Compile-Log*} buffer, and then
814 stops. The message may state a function name in which the error was
815 found, or it may not. Either way, here is how to find out where in the
816 file the error occurred.
818 What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
819 (Note that the buffer name starts with a space, so it does not show
820 up in @kbd{M-x list-buffers}.) This buffer contains the program being
821 compiled, and point shows how far the byte compiler was able to read.
823 If the error was due to invalid Lisp syntax, point shows exactly where
824 the invalid syntax was @emph{detected}. The cause of the error is not
825 necessarily near by! Use the techniques in the previous section to find
828 If the error was detected while compiling a form that had been read
829 successfully, then point is located at the end of the form. In this
830 case, this technique can't localize the error precisely, but can still
831 show you which function to check.
834 arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7