Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
ab422c4d PE |
3 | @c Copyright (C) 1990-1994, 1998-1999, 2001-2013 Free Software |
4 | @c Foundation, Inc. | |
b8d4c8d0 | 5 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 6 | @node Debugging |
b8d4c8d0 GM |
7 | @chapter Debugging Lisp Programs |
8 | ||
355cabc6 CY |
9 | There are several ways to find and investigate problems in an Emacs |
10 | Lisp program. | |
b8d4c8d0 GM |
11 | |
12 | @itemize @bullet | |
13 | @item | |
355cabc6 CY |
14 | If a problem occurs when you run the program, you can use the built-in |
15 | Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or | |
16 | alter its internal state. | |
b8d4c8d0 GM |
17 | |
18 | @item | |
355cabc6 | 19 | You can use Edebug, a source-level debugger for Emacs Lisp. |
b8d4c8d0 GM |
20 | |
21 | @item | |
355cabc6 CY |
22 | If a syntactic problem is preventing Lisp from even reading the |
23 | program, you can locate it using Lisp editing commands. | |
24 | ||
25 | @item | |
26 | You can look at the error and warning messages produced by the byte | |
27 | compiler when it compiles the program. @xref{Compiler Errors}. | |
28 | ||
29 | @item | |
30 | You can use the Testcover package to perform coverage testing on the | |
31 | program. | |
32 | ||
33 | @item | |
34 | You can use the ERT package to write regression tests for the program. | |
35 | @xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}. | |
b6729a18 GM |
36 | |
37 | @item | |
38 | You can profile the program to get hints about how to make it more efficient. | |
b8d4c8d0 GM |
39 | @end itemize |
40 | ||
355cabc6 CY |
41 | Other useful tools for debugging input and output problems are the |
42 | dribble file (@pxref{Terminal Input}) and the @code{open-termscript} | |
43 | function (@pxref{Terminal Output}). | |
44 | ||
b8d4c8d0 | 45 | @menu |
355cabc6 | 46 | * Debugger:: A debugger for the Emacs Lisp evaluator. |
d24880de | 47 | * Edebug:: A source-level Emacs Lisp debugger. |
b8d4c8d0 GM |
48 | * Syntax Errors:: How to find syntax errors. |
49 | * Test Coverage:: Ensuring you have tested all branches in your code. | |
5b776637 | 50 | * Profiling:: Measuring the resources that your code uses. |
b8d4c8d0 GM |
51 | @end menu |
52 | ||
b8d4c8d0 GM |
53 | @node Debugger |
54 | @section The Lisp Debugger | |
55 | @cindex debugger for Emacs Lisp | |
56 | @cindex Lisp debugger | |
57 | @cindex break | |
58 | ||
59 | The ordinary @dfn{Lisp debugger} provides the ability to suspend | |
60 | evaluation of a form. While evaluation is suspended (a state that is | |
61 | commonly known as a @dfn{break}), you may examine the run time stack, | |
62 | examine the values of local or global variables, or change those values. | |
63 | Since a break is a recursive edit, all the usual editing facilities of | |
64 | Emacs are available; you can even run programs that will enter the | |
65 | debugger recursively. @xref{Recursive Editing}. | |
66 | ||
67 | @menu | |
68 | * Error Debugging:: Entering the debugger when an error happens. | |
d24880de | 69 | * Infinite Loops:: Stopping and debugging a program that doesn't exit. |
b8d4c8d0 GM |
70 | * Function Debugging:: Entering it when a certain function is called. |
71 | * Explicit Debug:: Entering it at a certain point in the program. | |
72 | * Using Debugger:: What the debugger does; what you see while in it. | |
73 | * Debugger Commands:: Commands used while in the debugger. | |
74 | * Invoking the Debugger:: How to call the function @code{debug}. | |
75 | * Internals of Debugger:: Subroutines of the debugger, and global variables. | |
76 | @end menu | |
77 | ||
78 | @node Error Debugging | |
79 | @subsection Entering the Debugger on an Error | |
80 | @cindex error debugging | |
81 | @cindex debugging errors | |
82 | ||
83 | The most important time to enter the debugger is when a Lisp error | |
84 | happens. This allows you to investigate the immediate causes of the | |
85 | error. | |
86 | ||
87 | However, entry to the debugger is not a normal consequence of an | |
355cabc6 CY |
88 | error. Many commands signal Lisp errors when invoked inappropriately, |
89 | and during ordinary editing it would be very inconvenient to enter the | |
90 | debugger each time this happens. So if you want errors to enter the | |
91 | debugger, set the variable @code{debug-on-error} to non-@code{nil}. | |
92 | (The command @code{toggle-debug-on-error} provides an easy way to do | |
93 | this.) | |
b8d4c8d0 GM |
94 | |
95 | @defopt debug-on-error | |
260d5efc CY |
96 | This variable determines whether the debugger is called when an error |
97 | is signaled and not handled. If @code{debug-on-error} is @code{t}, | |
98 | all kinds of errors call the debugger, except those listed in | |
99 | @code{debug-ignored-errors} (see below). If it is @code{nil}, none | |
355cabc6 CY |
100 | call the debugger. |
101 | ||
102 | The value can also be a list of error conditions (@pxref{Signaling | |
103 | Errors}). Then the debugger is called only for error conditions in | |
104 | this list (except those also listed in @code{debug-ignored-errors}). | |
105 | For example, if you set @code{debug-on-error} to the list | |
106 | @code{(void-variable)}, the debugger is only called for errors about a | |
107 | variable that has no value. | |
b8d4c8d0 | 108 | |
355cabc6 CY |
109 | Note that @code{eval-expression-debug-on-error} overrides this |
110 | variable in some cases; see below. | |
b8d4c8d0 GM |
111 | |
112 | When this variable is non-@code{nil}, Emacs does not create an error | |
113 | handler around process filter functions and sentinels. Therefore, | |
114 | errors in these functions also invoke the debugger. @xref{Processes}. | |
115 | @end defopt | |
116 | ||
117 | @defopt debug-ignored-errors | |
355cabc6 CY |
118 | This variable specifies errors which should not enter the debugger, |
119 | regardless of the value of @code{debug-on-error}. Its value is a list | |
120 | of error condition symbols and/or regular expressions. If the error | |
121 | has any of those condition symbols, or if the error message matches | |
122 | any of the regular expressions, then that error does not enter the | |
123 | debugger. | |
124 | ||
38868ad7 GM |
125 | The normal value of this variable includes @code{user-error}, as well |
126 | as several errors that happen often during editing but rarely result | |
127 | from bugs in Lisp programs. However, ``rarely'' is not ``never''; if | |
128 | your program fails with an error that matches this list, you may try | |
129 | changing this list to debug the error. The easiest way is usually to | |
130 | set @code{debug-ignored-errors} to @code{nil}. | |
b8d4c8d0 GM |
131 | @end defopt |
132 | ||
133 | @defopt eval-expression-debug-on-error | |
355cabc6 CY |
134 | If this variable has a non-@code{nil} value (the default), running the |
135 | command @code{eval-expression} causes @code{debug-on-error} to be | |
136 | temporarily bound to to @code{t}. @xref{Lisp Eval,, Evaluating | |
b8d4c8d0 | 137 | Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. |
b8d4c8d0 | 138 | |
355cabc6 CY |
139 | If @code{eval-expression-debug-on-error} is @code{nil}, then the value |
140 | of @code{debug-on-error} is not changed during @code{eval-expression}. | |
7aa5aad8 GM |
141 | @end defopt |
142 | ||
355cabc6 CY |
143 | @defvar debug-on-signal |
144 | Normally, errors caught by @code{condition-case} never invoke the | |
145 | debugger. The @code{condition-case} gets a chance to handle the error | |
146 | before the debugger gets a chance. | |
147 | ||
148 | If you change @code{debug-on-signal} to a non-@code{nil} value, the | |
149 | debugger gets the first chance at every error, regardless of the | |
150 | presence of @code{condition-case}. (To invoke the debugger, the error | |
151 | must still fulfill the criteria specified by @code{debug-on-error} and | |
152 | @code{debug-ignored-errors}.) | |
153 | ||
154 | @strong{Warning:} Setting this variable to non-@code{nil} may have | |
155 | annoying effects. Various parts of Emacs catch errors in the normal | |
156 | course of affairs, and you may not even realize that errors happen | |
157 | there. If you need to debug code wrapped in @code{condition-case}, | |
158 | consider using @code{condition-case-unless-debug} (@pxref{Handling | |
159 | Errors}). | |
160 | @end defvar | |
161 | ||
7aa5aad8 GM |
162 | @defopt debug-on-event |
163 | If you set @code{debug-on-event} to a special event (@pxref{Special | |
164 | Events}), Emacs will try to enter the debugger as soon as it receives | |
165 | this event, bypassing @code{special-event-map}. At present, the only | |
166 | supported values correspond to the signals @code{SIGUSR1} and | |
649f602c GM |
167 | @code{SIGUSR2} (this is the default). This can be helpful when |
168 | @code{inhibit-quit} is set and Emacs is not otherwise responding. | |
b8d4c8d0 GM |
169 | @end defopt |
170 | ||
164f28b5 GM |
171 | @cindex message, finding what causes a particular message |
172 | @defvar debug-on-message | |
173 | If you set @code{debug-on-message} to a regular expression, | |
174 | Emacs will enter the debugger if it displays a matching message in the | |
175 | echo area. For example, this can be useful when trying to find the | |
176 | cause of a particular message. | |
177 | @end defvar | |
178 | ||
b8d4c8d0 GM |
179 | To debug an error that happens during loading of the init |
180 | file, use the option @samp{--debug-init}. This binds | |
181 | @code{debug-on-error} to @code{t} while loading the init file, and | |
182 | bypasses the @code{condition-case} which normally catches errors in the | |
183 | init file. | |
184 | ||
b8d4c8d0 GM |
185 | @node Infinite Loops |
186 | @subsection Debugging Infinite Loops | |
187 | @cindex infinite loops | |
188 | @cindex loops, infinite | |
189 | @cindex quitting from infinite loop | |
190 | @cindex stopping an infinite loop | |
191 | ||
192 | When a program loops infinitely and fails to return, your first | |
355cabc6 CY |
193 | problem is to stop the loop. On most operating systems, you can do |
194 | this with @kbd{C-g}, which causes a @dfn{quit}. @xref{Quitting}. | |
b8d4c8d0 GM |
195 | |
196 | Ordinary quitting gives no information about why the program was | |
197 | looping. To get more information, you can set the variable | |
355cabc6 CY |
198 | @code{debug-on-quit} to non-@code{nil}. Once you have the debugger |
199 | running in the middle of the infinite loop, you can proceed from the | |
200 | debugger using the stepping commands. If you step through the entire | |
201 | loop, you may get enough information to solve the problem. | |
b8d4c8d0 | 202 | |
355cabc6 CY |
203 | Quitting with @kbd{C-g} is not considered an error, and |
204 | @code{debug-on-error} has no effect on the handling of @kbd{C-g}. | |
205 | Likewise, @code{debug-on-quit} has no effect on errors. | |
b8d4c8d0 GM |
206 | |
207 | @defopt debug-on-quit | |
355cabc6 CY |
208 | This variable determines whether the debugger is called when |
209 | @code{quit} is signaled and not handled. If @code{debug-on-quit} is | |
210 | non-@code{nil}, then the debugger is called whenever you quit (that | |
211 | is, type @kbd{C-g}). If @code{debug-on-quit} is @code{nil} (the | |
212 | default), then the debugger is not called when you quit. | |
b8d4c8d0 GM |
213 | @end defopt |
214 | ||
215 | @node Function Debugging | |
216 | @subsection Entering the Debugger on a Function Call | |
217 | @cindex function call debugging | |
218 | @cindex debugging specific functions | |
219 | ||
220 | To investigate a problem that happens in the middle of a program, one | |
221 | useful technique is to enter the debugger whenever a certain function is | |
222 | called. You can do this to the function in which the problem occurs, | |
223 | and then step through the function, or you can do this to a function | |
224 | called shortly before the problem, step quickly over the call to that | |
225 | function, and then step through its caller. | |
226 | ||
227 | @deffn Command debug-on-entry function-name | |
228 | This function requests @var{function-name} to invoke the debugger each | |
229 | time it is called. It works by inserting the form | |
230 | @code{(implement-debug-on-entry)} into the function definition as the | |
231 | first form. | |
232 | ||
233 | Any function or macro defined as Lisp code may be set to break on | |
234 | entry, regardless of whether it is interpreted code or compiled code. | |
235 | If the function is a command, it will enter the debugger when called | |
236 | from Lisp and when called interactively (after the reading of the | |
237 | arguments). You can also set debug-on-entry for primitive functions | |
238 | (i.e., those written in C) this way, but it only takes effect when the | |
239 | primitive is called from Lisp code. Debug-on-entry is not allowed for | |
240 | special forms. | |
241 | ||
242 | When @code{debug-on-entry} is called interactively, it prompts for | |
243 | @var{function-name} in the minibuffer. If the function is already set | |
244 | up to invoke the debugger on entry, @code{debug-on-entry} does nothing. | |
245 | @code{debug-on-entry} always returns @var{function-name}. | |
246 | ||
247 | @strong{Warning:} if you redefine a function after using | |
248 | @code{debug-on-entry} on it, the code to enter the debugger is | |
249 | discarded by the redefinition. In effect, redefining the function | |
250 | cancels the break-on-entry feature for that function. | |
251 | ||
252 | Here's an example to illustrate use of this function: | |
253 | ||
254 | @example | |
255 | @group | |
256 | (defun fact (n) | |
257 | (if (zerop n) 1 | |
258 | (* n (fact (1- n))))) | |
259 | @result{} fact | |
260 | @end group | |
261 | @group | |
262 | (debug-on-entry 'fact) | |
263 | @result{} fact | |
264 | @end group | |
265 | @group | |
266 | (fact 3) | |
267 | @end group | |
268 | ||
269 | @group | |
270 | ------ Buffer: *Backtrace* ------ | |
271 | Debugger entered--entering a function: | |
272 | * fact(3) | |
273 | eval((fact 3)) | |
274 | eval-last-sexp-1(nil) | |
275 | eval-last-sexp(nil) | |
276 | call-interactively(eval-last-sexp) | |
277 | ------ Buffer: *Backtrace* ------ | |
278 | @end group | |
279 | ||
280 | @group | |
281 | (symbol-function 'fact) | |
282 | @result{} (lambda (n) | |
283 | (debug (quote debug)) | |
284 | (if (zerop n) 1 (* n (fact (1- n))))) | |
285 | @end group | |
286 | @end example | |
287 | @end deffn | |
288 | ||
289 | @deffn Command cancel-debug-on-entry &optional function-name | |
290 | This function undoes the effect of @code{debug-on-entry} on | |
291 | @var{function-name}. When called interactively, it prompts for | |
292 | @var{function-name} in the minibuffer. If @var{function-name} is | |
293 | omitted or @code{nil}, it cancels break-on-entry for all functions. | |
294 | Calling @code{cancel-debug-on-entry} does nothing to a function which is | |
295 | not currently set up to break on entry. | |
296 | @end deffn | |
297 | ||
298 | @node Explicit Debug | |
299 | @subsection Explicit Entry to the Debugger | |
300 | ||
301 | You can cause the debugger to be called at a certain point in your | |
302 | program by writing the expression @code{(debug)} at that point. To do | |
303 | this, visit the source file, insert the text @samp{(debug)} at the | |
304 | proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key | |
305 | binding). @strong{Warning:} if you do this for temporary debugging | |
306 | purposes, be sure to undo this insertion before you save the file! | |
307 | ||
308 | The place where you insert @samp{(debug)} must be a place where an | |
309 | additional form can be evaluated and its value ignored. (If the value | |
310 | of @code{(debug)} isn't ignored, it will alter the execution of the | |
311 | program!) The most common suitable places are inside a @code{progn} or | |
312 | an implicit @code{progn} (@pxref{Sequencing}). | |
313 | ||
7f7e0167 LI |
314 | If you don't know exactly where in the source code you want to put |
315 | the debug statement, but you want to display a backtrace when a | |
316 | certain message is displayed, you can set @code{debug-on-message} to a | |
317 | regular expression matching the desired message. | |
318 | ||
b8d4c8d0 GM |
319 | @node Using Debugger |
320 | @subsection Using the Debugger | |
321 | ||
322 | When the debugger is entered, it displays the previously selected | |
2bb0eca1 | 323 | buffer in one window and a buffer named @file{*Backtrace*} in another |
b8d4c8d0 GM |
324 | window. The backtrace buffer contains one line for each level of Lisp |
325 | function execution currently going on. At the beginning of this buffer | |
326 | is a message describing the reason that the debugger was invoked (such | |
327 | as the error message and associated data, if it was invoked due to an | |
328 | error). | |
329 | ||
57fc0fee | 330 | @vindex debugger-bury-or-kill |
b8d4c8d0 GM |
331 | The backtrace buffer is read-only and uses a special major mode, |
332 | Debugger mode, in which letters are defined as debugger commands. The | |
333 | usual Emacs editing commands are available; thus, you can switch windows | |
334 | to examine the buffer that was being edited at the time of the error, | |
335 | switch buffers, visit files, or do any other sort of editing. However, | |
336 | the debugger is a recursive editing level (@pxref{Recursive Editing}) | |
337 | and it is wise to go back to the backtrace buffer and exit the debugger | |
338 | (with the @kbd{q} command) when you are finished with it. Exiting | |
57fc0fee GM |
339 | the debugger gets out of the recursive edit and buries the backtrace |
340 | buffer. (You can customize what the @kbd{q} command does with the | |
341 | backtrace buffer by setting the variable @code{debugger-bury-or-kill}. | |
342 | For example, set it to @code{kill} if you prefer to kill the buffer | |
343 | rather than bury it. Consult the variable's documentation for more | |
344 | possibilities.) | |
b8d4c8d0 | 345 | |
66249842 LMI |
346 | When the debugger has been entered, the @code{debug-on-error} |
347 | variable is temporarily set according to | |
348 | @code{eval-expression-debug-on-error}. If the latter variable is | |
349 | non-@code{nil}, @code{debug-on-error} will temporarily be set to | |
350 | @code{t}. This means that any further errors that occur while doing a | |
351 | debugging session will (by default) trigger another backtrace. If | |
1bfe3177 | 352 | this is not what you want, you can either set |
66249842 LMI |
353 | @code{eval-expression-debug-on-error} to @code{nil}, or set |
354 | @code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. | |
355 | ||
b8d4c8d0 GM |
356 | @cindex current stack frame |
357 | The backtrace buffer shows you the functions that are executing and | |
358 | their argument values. It also allows you to specify a stack frame by | |
359 | moving point to the line describing that frame. (A stack frame is the | |
360 | place where the Lisp interpreter records information about a particular | |
361 | invocation of a function.) The frame whose line point is on is | |
362 | considered the @dfn{current frame}. Some of the debugger commands | |
363 | operate on the current frame. If a line starts with a star, that means | |
364 | that exiting that frame will call the debugger again. This is useful | |
365 | for examining the return value of a function. | |
366 | ||
367 | If a function name is underlined, that means the debugger knows | |
355cabc6 CY |
368 | where its source code is located. You can click with the mouse on |
369 | that name, or move to it and type @key{RET}, to visit the source code. | |
b8d4c8d0 GM |
370 | |
371 | The debugger itself must be run byte-compiled, since it makes | |
372 | assumptions about how many stack frames are used for the debugger | |
373 | itself. These assumptions are false if the debugger is running | |
374 | interpreted. | |
375 | ||
376 | @node Debugger Commands | |
377 | @subsection Debugger Commands | |
378 | @cindex debugger command list | |
379 | ||
380 | The debugger buffer (in Debugger mode) provides special commands in | |
381 | addition to the usual Emacs commands. The most important use of | |
382 | debugger commands is for stepping through code, so that you can see | |
383 | how control flows. The debugger can step through the control | |
384 | structures of an interpreted function, but cannot do so in a | |
385 | byte-compiled function. If you would like to step through a | |
386 | byte-compiled function, replace it with an interpreted definition of | |
387 | the same function. (To do this, visit the source for the function and | |
388 | type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger | |
389 | to step through a primitive function. | |
390 | ||
391 | Here is a list of Debugger mode commands: | |
392 | ||
393 | @table @kbd | |
394 | @item c | |
faccede1 CY |
395 | Exit the debugger and continue execution. This resumes execution of |
396 | the program as if the debugger had never been entered (aside from any | |
397 | side-effects that you caused by changing variable values or data | |
398 | structures while inside the debugger). | |
b8d4c8d0 GM |
399 | |
400 | @item d | |
401 | Continue execution, but enter the debugger the next time any Lisp | |
402 | function is called. This allows you to step through the | |
403 | subexpressions of an expression, seeing what values the subexpressions | |
404 | compute, and what else they do. | |
405 | ||
406 | The stack frame made for the function call which enters the debugger in | |
407 | this way will be flagged automatically so that the debugger will be | |
408 | called again when the frame is exited. You can use the @kbd{u} command | |
409 | to cancel this flag. | |
410 | ||
411 | @item b | |
412 | Flag the current frame so that the debugger will be entered when the | |
413 | frame is exited. Frames flagged in this way are marked with stars | |
414 | in the backtrace buffer. | |
415 | ||
416 | @item u | |
417 | Don't enter the debugger when the current frame is exited. This | |
418 | cancels a @kbd{b} command on that frame. The visible effect is to | |
419 | remove the star from the line in the backtrace buffer. | |
420 | ||
421 | @item j | |
422 | Flag the current frame like @kbd{b}. Then continue execution like | |
423 | @kbd{c}, but temporarily disable break-on-entry for all functions that | |
424 | are set up to do so by @code{debug-on-entry}. | |
425 | ||
426 | @item e | |
427 | Read a Lisp expression in the minibuffer, evaluate it, and print the | |
428 | value in the echo area. The debugger alters certain important | |
429 | variables, and the current buffer, as part of its operation; @kbd{e} | |
430 | temporarily restores their values from outside the debugger, so you can | |
431 | examine and change them. This makes the debugger more transparent. By | |
432 | contrast, @kbd{M-:} does nothing special in the debugger; it shows you | |
433 | the variable values within the debugger. | |
434 | ||
435 | @item R | |
436 | Like @kbd{e}, but also save the result of evaluation in the | |
2bb0eca1 | 437 | buffer @file{*Debugger-record*}. |
b8d4c8d0 GM |
438 | |
439 | @item q | |
440 | Terminate the program being debugged; return to top-level Emacs | |
441 | command execution. | |
442 | ||
443 | If the debugger was entered due to a @kbd{C-g} but you really want | |
444 | to quit, and not debug, use the @kbd{q} command. | |
445 | ||
446 | @item r | |
447 | Return a value from the debugger. The value is computed by reading an | |
448 | expression with the minibuffer and evaluating it. | |
449 | ||
450 | The @kbd{r} command is useful when the debugger was invoked due to exit | |
451 | from a Lisp call frame (as requested with @kbd{b} or by entering the | |
452 | frame with @kbd{d}); then the value specified in the @kbd{r} command is | |
453 | used as the value of that frame. It is also useful if you call | |
454 | @code{debug} and use its return value. Otherwise, @kbd{r} has the same | |
455 | effect as @kbd{c}, and the specified return value does not matter. | |
456 | ||
457 | You can't use @kbd{r} when the debugger was entered due to an error. | |
458 | ||
459 | @item l | |
460 | Display a list of functions that will invoke the debugger when called. | |
461 | This is a list of functions that are set to break on entry by means of | |
462 | @code{debug-on-entry}. @strong{Warning:} if you redefine such a | |
463 | function and thus cancel the effect of @code{debug-on-entry}, it may | |
464 | erroneously show up in this list. | |
465 | @end table | |
466 | ||
467 | @node Invoking the Debugger | |
468 | @subsection Invoking the Debugger | |
469 | ||
470 | Here we describe in full detail the function @code{debug} that is used | |
471 | to invoke the debugger. | |
472 | ||
0b128ac4 | 473 | @deffn Command debug &rest debugger-args |
b8d4c8d0 | 474 | This function enters the debugger. It switches buffers to a buffer |
2bb0eca1 | 475 | named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second |
b8d4c8d0 GM |
476 | recursive entry to the debugger, etc.), and fills it with information |
477 | about the stack of Lisp function calls. It then enters a recursive | |
478 | edit, showing the backtrace buffer in Debugger mode. | |
479 | ||
480 | The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit | |
481 | the recursive edit; then @code{debug} switches back to the previous | |
482 | buffer and returns to whatever called @code{debug}. This is the only | |
483 | way the function @code{debug} can return to its caller. | |
484 | ||
485 | The use of the @var{debugger-args} is that @code{debug} displays the | |
2bb0eca1 | 486 | rest of its arguments at the top of the @file{*Backtrace*} buffer, so |
b8d4c8d0 GM |
487 | that the user can see them. Except as described below, this is the |
488 | @emph{only} way these arguments are used. | |
489 | ||
490 | However, certain values for first argument to @code{debug} have a | |
491 | special significance. (Normally, these values are used only by the | |
492 | internals of Emacs, and not by programmers calling @code{debug}.) Here | |
493 | is a table of these special values: | |
494 | ||
495 | @table @code | |
496 | @item lambda | |
497 | @cindex @code{lambda} in debug | |
498 | A first argument of @code{lambda} means @code{debug} was called | |
499 | because of entry to a function when @code{debug-on-next-call} was | |
500 | non-@code{nil}. The debugger displays @samp{Debugger | |
501 | entered--entering a function:} as a line of text at the top of the | |
502 | buffer. | |
503 | ||
504 | @item debug | |
505 | @code{debug} as first argument means @code{debug} was called because | |
506 | of entry to a function that was set to debug on entry. The debugger | |
507 | displays the string @samp{Debugger entered--entering a function:}, | |
508 | just as in the @code{lambda} case. It also marks the stack frame for | |
509 | that function so that it will invoke the debugger when exited. | |
510 | ||
511 | @item t | |
512 | When the first argument is @code{t}, this indicates a call to | |
513 | @code{debug} due to evaluation of a function call form when | |
514 | @code{debug-on-next-call} is non-@code{nil}. The debugger displays | |
515 | @samp{Debugger entered--beginning evaluation of function call form:} | |
516 | as the top line in the buffer. | |
517 | ||
518 | @item exit | |
519 | When the first argument is @code{exit}, it indicates the exit of a | |
520 | stack frame previously marked to invoke the debugger on exit. The | |
521 | second argument given to @code{debug} in this case is the value being | |
522 | returned from the frame. The debugger displays @samp{Debugger | |
523 | entered--returning value:} in the top line of the buffer, followed by | |
524 | the value being returned. | |
525 | ||
526 | @item error | |
527 | @cindex @code{error} in debug | |
528 | When the first argument is @code{error}, the debugger indicates that | |
529 | it is being entered because an error or @code{quit} was signaled and | |
530 | not handled, by displaying @samp{Debugger entered--Lisp error:} | |
531 | followed by the error signaled and any arguments to @code{signal}. | |
532 | For example, | |
533 | ||
534 | @example | |
535 | @group | |
536 | (let ((debug-on-error t)) | |
537 | (/ 1 0)) | |
538 | @end group | |
539 | ||
540 | @group | |
541 | ------ Buffer: *Backtrace* ------ | |
542 | Debugger entered--Lisp error: (arith-error) | |
543 | /(1 0) | |
544 | ... | |
545 | ------ Buffer: *Backtrace* ------ | |
546 | @end group | |
547 | @end example | |
548 | ||
549 | If an error was signaled, presumably the variable | |
550 | @code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, | |
551 | then presumably the variable @code{debug-on-quit} is non-@code{nil}. | |
552 | ||
553 | @item nil | |
554 | Use @code{nil} as the first of the @var{debugger-args} when you want | |
555 | to enter the debugger explicitly. The rest of the @var{debugger-args} | |
556 | are printed on the top line of the buffer. You can use this feature to | |
557 | display messages---for example, to remind yourself of the conditions | |
558 | under which @code{debug} is called. | |
559 | @end table | |
0b128ac4 | 560 | @end deffn |
b8d4c8d0 GM |
561 | |
562 | @node Internals of Debugger | |
563 | @subsection Internals of the Debugger | |
564 | ||
565 | This section describes functions and variables used internally by the | |
566 | debugger. | |
567 | ||
568 | @defvar debugger | |
569 | The value of this variable is the function to call to invoke the | |
570 | debugger. Its value must be a function of any number of arguments, or, | |
571 | more typically, the name of a function. This function should invoke | |
572 | some kind of debugger. The default value of the variable is | |
573 | @code{debug}. | |
574 | ||
575 | The first argument that Lisp hands to the function indicates why it | |
576 | was called. The convention for arguments is detailed in the description | |
577 | of @code{debug} (@pxref{Invoking the Debugger}). | |
578 | @end defvar | |
579 | ||
580 | @deffn Command backtrace | |
581 | @cindex run time stack | |
582 | @cindex call stack | |
583 | This function prints a trace of Lisp function calls currently active. | |
584 | This is the function used by @code{debug} to fill up the | |
2bb0eca1 | 585 | @file{*Backtrace*} buffer. It is written in C, since it must have access |
b8d4c8d0 GM |
586 | to the stack to determine which function calls are active. The return |
587 | value is always @code{nil}. | |
588 | ||
589 | In the following example, a Lisp expression calls @code{backtrace} | |
590 | explicitly. This prints the backtrace to the stream | |
591 | @code{standard-output}, which, in this case, is the buffer | |
592 | @samp{backtrace-output}. | |
593 | ||
594 | Each line of the backtrace represents one function call. The line shows | |
595 | the values of the function's arguments if they are all known; if they | |
596 | are still being computed, the line says so. The arguments of special | |
597 | forms are elided. | |
598 | ||
599 | @smallexample | |
600 | @group | |
601 | (with-output-to-temp-buffer "backtrace-output" | |
602 | (let ((var 1)) | |
603 | (save-excursion | |
604 | (setq var (eval '(progn | |
605 | (1+ var) | |
606 | (list 'testing (backtrace)))))))) | |
607 | ||
608 | @result{} (testing nil) | |
609 | @end group | |
610 | ||
611 | @group | |
612 | ----------- Buffer: backtrace-output ------------ | |
613 | backtrace() | |
614 | (list ...computing arguments...) | |
615 | @end group | |
616 | (progn ...) | |
617 | eval((progn (1+ var) (list (quote testing) (backtrace)))) | |
618 | (setq ...) | |
619 | (save-excursion ...) | |
620 | (let ...) | |
621 | (with-output-to-temp-buffer ...) | |
622 | eval((with-output-to-temp-buffer ...)) | |
623 | eval-last-sexp-1(nil) | |
624 | @group | |
625 | eval-last-sexp(nil) | |
626 | call-interactively(eval-last-sexp) | |
627 | ----------- Buffer: backtrace-output ------------ | |
628 | @end group | |
629 | @end smallexample | |
630 | @end deffn | |
631 | ||
b8d4c8d0 GM |
632 | @defvar debug-on-next-call |
633 | @cindex @code{eval}, and debugging | |
634 | @cindex @code{apply}, and debugging | |
635 | @cindex @code{funcall}, and debugging | |
636 | If this variable is non-@code{nil}, it says to call the debugger before | |
637 | the next @code{eval}, @code{apply} or @code{funcall}. Entering the | |
638 | debugger sets @code{debug-on-next-call} to @code{nil}. | |
639 | ||
640 | The @kbd{d} command in the debugger works by setting this variable. | |
641 | @end defvar | |
642 | ||
643 | @defun backtrace-debug level flag | |
644 | This function sets the debug-on-exit flag of the stack frame @var{level} | |
645 | levels down the stack, giving it the value @var{flag}. If @var{flag} is | |
646 | non-@code{nil}, this will cause the debugger to be entered when that | |
647 | frame later exits. Even a nonlocal exit through that frame will enter | |
648 | the debugger. | |
649 | ||
650 | This function is used only by the debugger. | |
651 | @end defun | |
652 | ||
653 | @defvar command-debug-status | |
654 | This variable records the debugging status of the current interactive | |
655 | command. Each time a command is called interactively, this variable is | |
656 | bound to @code{nil}. The debugger can set this variable to leave | |
657 | information for future debugger invocations during the same command | |
658 | invocation. | |
659 | ||
660 | The advantage of using this variable rather than an ordinary global | |
661 | variable is that the data will never carry over to a subsequent command | |
662 | invocation. | |
663 | @end defvar | |
664 | ||
665 | @defun backtrace-frame frame-number | |
666 | The function @code{backtrace-frame} is intended for use in Lisp | |
667 | debuggers. It returns information about what computation is happening | |
668 | in the stack frame @var{frame-number} levels down. | |
669 | ||
670 | If that frame has not evaluated the arguments yet, or is a special | |
671 | form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. | |
672 | ||
673 | If that frame has evaluated its arguments and called its function | |
674 | already, the return value is @code{(t @var{function} | |
675 | @var{arg-values}@dots{})}. | |
676 | ||
677 | In the return value, @var{function} is whatever was supplied as the | |
678 | @sc{car} of the evaluated list, or a @code{lambda} expression in the | |
679 | case of a macro call. If the function has a @code{&rest} argument, that | |
680 | is represented as the tail of the list @var{arg-values}. | |
681 | ||
682 | If @var{frame-number} is out of range, @code{backtrace-frame} returns | |
683 | @code{nil}. | |
684 | @end defun | |
685 | ||
686 | @include edebug.texi | |
687 | ||
688 | @node Syntax Errors | |
689 | @section Debugging Invalid Lisp Syntax | |
690 | @cindex debugging invalid Lisp syntax | |
691 | ||
692 | The Lisp reader reports invalid syntax, but cannot say where the real | |
693 | problem is. For example, the error ``End of file during parsing'' in | |
694 | evaluating an expression indicates an excess of open parentheses (or | |
695 | square brackets). The reader detects this imbalance at the end of the | |
696 | file, but it cannot figure out where the close parenthesis should have | |
697 | been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close | |
698 | parenthesis or missing open parenthesis, but does not say where the | |
699 | missing parenthesis belongs. How, then, to find what to change? | |
700 | ||
701 | If the problem is not simply an imbalance of parentheses, a useful | |
702 | technique is to try @kbd{C-M-e} at the beginning of each defun, and see | |
703 | if it goes to the place where that defun appears to end. If it does | |
704 | not, there is a problem in that defun. | |
705 | ||
706 | @cindex unbalanced parentheses | |
707 | @cindex parenthesis mismatch, debugging | |
708 | However, unmatched parentheses are the most common syntax errors in | |
709 | Lisp, and we can give further advice for those cases. (In addition, | |
710 | just moving point through the code with Show Paren mode enabled might | |
711 | find the mismatch.) | |
712 | ||
713 | @menu | |
714 | * Excess Open:: How to find a spurious open paren or missing close. | |
715 | * Excess Close:: How to find a spurious close paren or missing open. | |
716 | @end menu | |
717 | ||
718 | @node Excess Open | |
719 | @subsection Excess Open Parentheses | |
720 | ||
721 | The first step is to find the defun that is unbalanced. If there is | |
722 | an excess open parenthesis, the way to do this is to go to the end of | |
723 | the file and type @kbd{C-u C-M-u}. This will move you to the | |
724 | beginning of the first defun that is unbalanced. | |
725 | ||
726 | The next step is to determine precisely what is wrong. There is no | |
727 | way to be sure of this except by studying the program, but often the | |
728 | existing indentation is a clue to where the parentheses should have | |
729 | been. The easiest way to use this clue is to reindent with @kbd{C-M-q} | |
730 | and see what moves. @strong{But don't do this yet!} Keep reading, | |
731 | first. | |
732 | ||
733 | Before you do this, make sure the defun has enough close parentheses. | |
734 | Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest | |
735 | of the file until the end. So move to the end of the defun and insert a | |
736 | close parenthesis there. Don't use @kbd{C-M-e} to move there, since | |
737 | that too will fail to work until the defun is balanced. | |
738 | ||
739 | Now you can go to the beginning of the defun and type @kbd{C-M-q}. | |
740 | Usually all the lines from a certain point to the end of the function | |
741 | will shift to the right. There is probably a missing close parenthesis, | |
742 | or a superfluous open parenthesis, near that point. (However, don't | |
743 | assume this is true; study the code to make sure.) Once you have found | |
744 | the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old | |
745 | indentation is probably appropriate to the intended parentheses. | |
746 | ||
747 | After you think you have fixed the problem, use @kbd{C-M-q} again. If | |
748 | the old indentation actually fit the intended nesting of parentheses, | |
749 | and you have put back those parentheses, @kbd{C-M-q} should not change | |
750 | anything. | |
751 | ||
752 | @node Excess Close | |
753 | @subsection Excess Close Parentheses | |
754 | ||
755 | To deal with an excess close parenthesis, first go to the beginning | |
756 | of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first | |
757 | unbalanced defun. | |
758 | ||
759 | Then find the actual matching close parenthesis by typing @kbd{C-M-f} | |
760 | at the beginning of that defun. This will leave you somewhere short of | |
761 | the place where the defun ought to end. It is possible that you will | |
762 | find a spurious close parenthesis in that vicinity. | |
763 | ||
764 | If you don't see a problem at that point, the next thing to do is to | |
765 | type @kbd{C-M-q} at the beginning of the defun. A range of lines will | |
766 | probably shift left; if so, the missing open parenthesis or spurious | |
767 | close parenthesis is probably near the first of those lines. (However, | |
768 | don't assume this is true; study the code to make sure.) Once you have | |
769 | found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the | |
770 | old indentation is probably appropriate to the intended parentheses. | |
771 | ||
772 | After you think you have fixed the problem, use @kbd{C-M-q} again. If | |
773 | the old indentation actually fits the intended nesting of parentheses, | |
774 | and you have put back those parentheses, @kbd{C-M-q} should not change | |
775 | anything. | |
776 | ||
777 | @node Test Coverage | |
778 | @section Test Coverage | |
779 | @cindex coverage testing | |
780 | ||
781 | @findex testcover-start | |
782 | @findex testcover-mark-all | |
783 | @findex testcover-next-mark | |
784 | You can do coverage testing for a file of Lisp code by loading the | |
785 | @code{testcover} library and using the command @kbd{M-x | |
786 | testcover-start @key{RET} @var{file} @key{RET}} to instrument the | |
787 | code. Then test your code by calling it one or more times. Then use | |
788 | the command @kbd{M-x testcover-mark-all} to display colored highlights | |
789 | on the code to show where coverage is insufficient. The command | |
790 | @kbd{M-x testcover-next-mark} will move point forward to the next | |
791 | highlighted spot. | |
792 | ||
793 | Normally, a red highlight indicates the form was never completely | |
794 | evaluated; a brown highlight means it always evaluated to the same | |
795 | value (meaning there has been little testing of what is done with the | |
796 | result). However, the red highlight is skipped for forms that can't | |
797 | possibly complete their evaluation, such as @code{error}. The brown | |
798 | highlight is skipped for forms that are expected to always evaluate to | |
799 | the same value, such as @code{(setq x 14)}. | |
800 | ||
801 | For difficult cases, you can add do-nothing macros to your code to | |
802 | give advice to the test coverage tool. | |
803 | ||
804 | @defmac 1value form | |
805 | Evaluate @var{form} and return its value, but inform coverage testing | |
806 | that @var{form}'s value should always be the same. | |
807 | @end defmac | |
808 | ||
809 | @defmac noreturn form | |
810 | Evaluate @var{form}, informing coverage testing that @var{form} should | |
811 | never return. If it ever does return, you get a run-time error. | |
812 | @end defmac | |
813 | ||
814 | Edebug also has a coverage testing feature (@pxref{Coverage | |
815 | Testing}). These features partly duplicate each other, and it would | |
816 | be cleaner to combine them. | |
5b776637 GM |
817 | |
818 | ||
819 | @node Profiling | |
820 | @section Profiling | |
821 | @cindex profiling | |
822 | @cindex measuring resource usage | |
823 | @cindex memory usage | |
824 | ||
825 | If your program is working correctly, but you want to make it run more | |
826 | quickly or efficiently, the first thing to do is @dfn{profile} your | |
1faaca8a | 827 | code so that you know how it is using resources. If you find that one |
5b776637 | 828 | particular function is responsible for a significant portion of the |
1faaca8a | 829 | runtime, you can start looking for ways to optimize that piece. |
5b776637 GM |
830 | |
831 | Emacs has built-in support for this. To begin profiling, type | |
832 | @kbd{M-x profiler-start}. You can choose to profile by processor | |
833 | usage, memory usage, or both. After doing some work, type | |
834 | @kbd{M-x profiler-report} to display a summary buffer for each | |
835 | resource that you chose to profile. The names of the report buffers | |
836 | include the times at which the reports were generated, so you can | |
837 | generate another report later on without erasing previous results. | |
838 | When you have finished profiling, type @kbd{M-x profiler-stop} (there | |
839 | is a small overhead associated with profiling). | |
840 | ||
b6729a18 GM |
841 | The profiler report buffer shows, on each line, a function that was |
842 | called, followed by how much resource (processor or memory) it used in | |
843 | absolute and percentage times since profiling started. If a given | |
844 | line has a @samp{+} symbol at the left-hand side, you can expand that | |
845 | line by typing @key{RET}, in order to see the function(s) called by | |
846 | the higher-level function. Pressing @key{RET} again will collapse | |
847 | back to the original state. | |
848 | ||
849 | Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function. | |
850 | Press @kbd{d} to view a function's documentation. | |
851 | You can save a profile to a file using @kbd{C-x C-w}. | |
852 | You can compare two profiles using @kbd{=}. | |
5b776637 | 853 | |
b6729a18 | 854 | @c FIXME reversed calltree? |
5b776637 GM |
855 | |
856 | @cindex @file{elp.el} | |
857 | @cindex timing programs | |
858 | The @file{elp} library offers an alternative approach. See the file | |
859 | @file{elp.el} for instructions. | |
860 | ||
861 | @cindex @file{benchmark.el} | |
862 | @cindex benchmarking | |
863 | You can check the speed of individual Emacs Lisp forms using the | |
864 | @file{benchmark} library. See the functions @code{benchmark-run} and | |
865 | @code{benchmark-run-compiled} in @file{benchmark.el}. | |
38a2f917 GM |
866 | |
867 | @c Not worth putting in the printed manual. | |
868 | @ifnottex | |
869 | @cindex --enable-profiling option of configure | |
365fc14a | 870 | To profile Emacs at the level of its C code, you can build it using the |
38a2f917 GM |
871 | @option{--enable-profiling} option of @command{configure}. When Emacs |
872 | exits, it generates a file @file{gmon.out} that you can examine using | |
873 | the @command{gprof} utility. This feature is mainly useful for | |
874 | debugging Emacs. It actually stops the Lisp-level @kbd{M-x | |
875 | profiler-@dots{}} commands described above from working. | |
876 | @end ifnottex |