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