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