Mercurial > hg > xemacs-beta
annotate man/lispref/debugging.texi @ 5146:88bd4f3ef8e4
make lrecord UID's have a separate UID space for each object, resurrect debug SOE code in extents.c
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-03-15 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (c_readonly):
* alloc.c (deadbeef_memory):
* alloc.c (make_compiled_function):
* alloc.c (make_button_data):
* alloc.c (make_motion_data):
* alloc.c (make_process_data):
* alloc.c (make_timeout_data):
* alloc.c (make_magic_data):
* alloc.c (make_magic_eval_data):
* alloc.c (make_eval_data):
* alloc.c (make_misc_user_data):
* alloc.c (noseeum_make_marker):
* alloc.c (ADDITIONAL_FREE_string):
* alloc.c (common_init_alloc_early):
* alloc.c (init_alloc_once_early):
* bytecode.c (print_compiled_function):
* bytecode.c (mark_compiled_function):
* casetab.c:
* casetab.c (print_case_table):
* console.c:
* console.c (print_console):
* database.c (print_database):
* database.c (finalize_database):
* device-msw.c (sync_printer_with_devmode):
* device-msw.c (print_devmode):
* device-msw.c (finalize_devmode):
* device.c:
* device.c (print_device):
* elhash.c:
* elhash.c (print_hash_table):
* eval.c (print_multiple_value):
* eval.c (mark_multiple_value):
* events.c (deinitialize_event):
* events.c (print_event):
* events.c (event_equal):
* extents.c:
* extents.c (soe_dump):
* extents.c (soe_insert):
* extents.c (soe_delete):
* extents.c (soe_move):
* extents.c (extent_fragment_update):
* extents.c (print_extent_1):
* extents.c (print_extent):
* extents.c (vars_of_extents):
* frame.c:
* frame.c (print_frame):
* free-hook.c:
* free-hook.c (check_free):
* glyphs.c:
* glyphs.c (print_image_instance):
* glyphs.c (print_glyph):
* gui.c:
* gui.c (copy_gui_item):
* hash.c:
* hash.c (NULL_ENTRY):
* hash.c (KEYS_DIFFER_P):
* keymap.c (print_keymap):
* keymap.c (MARKED_SLOT):
* lisp.h:
* lrecord.h:
* lrecord.h (LISP_OBJECT_UID):
* lrecord.h (set_lheader_implementation):
* lrecord.h (struct old_lcrecord_header):
* lstream.c (print_lstream):
* lstream.c (finalize_lstream):
* marker.c (print_marker):
* marker.c (marker_equal):
* mc-alloc.c (visit_all_used_page_headers):
* mule-charset.c:
* mule-charset.c (print_charset):
* objects.c (print_color_instance):
* objects.c (print_font_instance):
* objects.c (finalize_font_instance):
* opaque.c (print_opaque):
* opaque.c (print_opaque_ptr):
* opaque.c (equal_opaque_ptr):
* print.c (internal_object_printer):
* print.c (enum printing_badness):
* rangetab.c (print_range_table):
* rangetab.c (range_table_equal):
* specifier.c (print_specifier):
* specifier.c (finalize_specifier):
* symbols.c:
* symbols.c (print_symbol_value_magic):
* tooltalk.c:
* tooltalk.c (print_tooltalk_message):
* tooltalk.c (print_tooltalk_pattern):
* window.c (print_window):
* window.c (debug_print_window):
(1) Make lrecord UID's have a separate UID space for each object.
Otherwise, with 20-bit UID's, we rapidly wrap around, especially
when common objects like conses and strings increment the UID value
for every object created. (Originally I tried making two UID spaces,
one for objects that always print readably and hence don't display
the UID, and one for other objects. But certain objects like markers
for which a UID is displayed are still generated rapidly enough that
UID overflow is a serious issue.) This also has the advantage of
making UID values smaller, hence easier to remember -- their main
purpose is to make it easier to keep track of different objects of
the same type when debugging code. Make sure we dump lrecord UID's
so that we don't have problems with pdumped and non-dumped objects
having the same UID.
(2) Display UID's consistently whenever an object (a) doesn't
consistently print readably (objects like cons and string, which
always print readably, can't display a UID), and (b) doesn't
otherwise have a unique property that makes objects of a
particular type distinguishable. (E.g. buffers didn't and still
don't print an ID, but the buffer name uniquely identifies the
buffer.) Some types, such as event, extent, compiled-function,
didn't always (or didn't ever) display an ID; others (such as
marker, extent, lstream, opaque, opaque-ptr, any object using
internal_object_printer()) used to display the actual machine
pointer instead.
(3) Rename NORMAL_LISP_OBJECT_UID to LISP_OBJECT_UID; make it work
over all Lisp objects and take a Lisp object, not a struct pointer.
(4) Some misc cleanups in alloc.c, elhash.c.
(5) Change code in events.c that "deinitializes" an event so that
it doesn't increment the event UID counter in the process. Also
use deadbeef_memory() to overwrite memory instead of doing the same
with custom code. In the process, make deadbeef_memory() in
alloc.c always available, and delete extraneous copy in mc-alloc.c.
Also capitalize all uses of 0xDEADBEEF. Similarly in elhash.c
call deadbeef_memory().
(6) Resurrect "debug SOE" code in extents.c. Make it conditional
on DEBUG_XEMACS and on a `debug-soe' variable, rather than on
SOE_DEBUG. Make it output to stderr, not stdout.
(7) Delete some custom print methods that were identical to
external_object_printer().
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Mon, 15 Mar 2010 16:35:38 -0500 |
| parents | 755ae5b97edb |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 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 | |
| 438 | 98 @defopt debug-on-signal |
| 99 This variable is similar to @code{debug-on-error} but breaks | |
| 100 whenever an error is signalled, regardless of whether it would be | |
| 101 handled. | |
| 102 @end defopt | |
| 103 | |
| 428 | 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 | |
| 113 during editing but rarely result from bugs in Lisp programs. | |
| 114 @end defopt | |
| 115 | |
| 116 To debug an error that happens during loading of the @file{.emacs} | |
| 117 file, use the option @samp{-debug-init}, which binds | |
| 118 @code{debug-on-error} to @code{t} while @file{.emacs} is loaded and | |
| 119 inhibits use of @code{condition-case} to catch init file errors. | |
| 120 | |
| 121 If your @file{.emacs} file sets @code{debug-on-error}, the effect may | |
| 122 not last past the end of loading @file{.emacs}. (This is an undesirable | |
| 123 byproduct of the code that implements the @samp{-debug-init} command | |
| 124 line option.) The best way to make @file{.emacs} set | |
| 125 @code{debug-on-error} permanently is with @code{after-init-hook}, like | |
| 126 this: | |
| 127 | |
| 128 @example | |
| 129 (add-hook 'after-init-hook | |
| 130 '(lambda () (setq debug-on-error t))) | |
| 131 @end example | |
| 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{Please 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 | |
| 444 | 235 @deffn Command cancel-debug-on-entry &optional function-name |
| 428 | 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. | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
532 The arguments of special operators are elided. |
| 428 | 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 |