annotate man/lispref/debugging.texi @ 4885:6772ce4d982b

Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums lisp/ChangeLog addition: 2010-01-24 Aidan Kehoe <kehoea@parhasard.net> Correct the semantics of #'member*, #'eql, #'assoc* in the presence of bignums; change the integerp byte code to fixnump semantics. * bytecomp.el (fixnump, integerp, byte-compile-integerp): Change the integerp byte code to fixnump; add a byte-compile method to integerp using fixnump and numberp and avoiding a funcall most of the time, since in the non-core contexts where integerp is used, it's mostly distinguishing between fixnums and things that are not numbers at all. * byte-optimize.el (side-effect-free-fns, byte-after-unbind-ops) (byte-compile-side-effect-and-error-free-ops): Replace the integerp bytecode with fixnump; add fixnump to the side-effect-free-fns. Add the other extended number type predicates to the list in passing. * obsolete.el (floatp-safe): Mark this as obsolete. * cl.el (eql): Go into more detail in the docstring here. Don't bother checking whether both arguments are numbers; one is enough, #'equal will fail correctly if they have distinct types. (subst): Replace a call to #'integerp (deciding whether to use #'memq or not) with one to #'fixnump. Delete most-positive-fixnum, most-negative-fixnum from this file; they're now always in C, so they can't be modified from Lisp. * cl-seq.el (member*, assoc*, rassoc*): Correct these functions in the presence of bignums. * cl-macs.el (cl-make-type-test): The type test for a fixnum is now fixnump. Ditch floatp-safe, use floatp instead. (eql): Correct this compiler macro in the presence of bignums. (assoc*): Correct this compiler macro in the presence of bignums. * simple.el (undo): Change #'integerp to #'fixnump here, since we use #'delq with the same value as ELT a few lines down. src/ChangeLog addition: 2010-01-24 Aidan Kehoe <kehoea@parhasard.net> Fix problems with #'eql, extended number types, and the hash table implementation; change the Bintegerp bytecode to fixnump semantics even on bignum builds, since #'integerp can have a fast implementation in terms of #'fixnump for most of its extant uses, but not vice-versa. * lisp.h: Always #include number.h; we want the macros provided in it, even if the various number types are not available. * number.h (NON_FIXNUM_NUMBER_P): New macro, giving 1 when its argument is of non-immediate number type. Equivalent to FLOATP if WITH_NUMBER_TYPES is not defined. * elhash.c (lisp_object_eql_equal, lisp_object_eql_hash): Use NON_FIXNUM_NUMBER_P in these functions, instead of FLOATP, giving more correct behaviour in the presence of the extended number types. * bytecode.c (Bfixnump, execute_optimized_program): Rename Bintegerp to Bfixnump; change its semantics to reflect the new name on builds with bignum support. * data.c (Ffixnump, Fintegerp, syms_of_data, vars_of_data): Always make #'fixnump available, even on non-BIGNUM builds; always implement #'integerp in this file, even on BIGNUM builds. Move most-positive-fixnum, most-negative-fixnum here from number.c, so they are Lisp constants even on builds without number types, and attempts to change or bind them error. Use the NUMBERP and INTEGERP macros even on builds without extended number types. * data.c (fixnum_char_or_marker_to_int): Rename this function from integer_char_or_marker_to_int, to better reflect the arguments it accepts. * number.c (Fevenp, Foddp, syms_of_number): Never provide #'integerp in this file. Remove #'oddp, #'evenp; their implementations are overridden by those in cl.el. * number.c (vars_of_number): most-positive-fixnum, most-negative-fixnum are no longer here. man/ChangeLog addition: 2010-01-23 Aidan Kehoe <kehoea@parhasard.net> Generally: be careful to say fixnum, not integer, when talking about fixed-precision integral types. I'm sure I've missed instances, both here and in the docstrings, but this is a decent start. * lispref/text.texi (Columns): Document where only fixnums, not integers generally, are accepted. (Registers): Remove some ancient char-int confoundance here. * lispref/strings.texi (Creating Strings, Creating Strings): Be more exact in describing where fixnums but not integers in general are accepted. (Creating Strings): Use a more contemporary example to illustrate how concat deals with lists including integers about #xFF. Delete some obsolete documentation on same. (Char Table Types): Document that only fixnums are accepted as values in syntax tables. * lispref/searching.texi (String Search, Search and Replace): Be exact in describing where fixnums but not integers in general are accepted. * lispref/range-tables.texi (Range Tables): Be exact in describing them; only fixnums are accepted to describe ranges. * lispref/os.texi (Killing XEmacs, User Identification) (Time of Day, Time Conversion): Be more exact about using fixnum where only fixed-precision integers are accepted. * lispref/objects.texi (Integer Type): Be more exact (and up-to-date) about the possible values for integers. Cross-reference to documentation of the bignum extension. (Equality Predicates): (Range Table Type): (Array Type): Use fixnum, not integer, to describe a fixed-precision integer. (Syntax Table Type): Correct some English syntax here. * lispref/numbers.texi (Numbers): Change the phrasing here to use fixnum to mean the fixed-precision integers normal in emacs. Document that our terminology deviates from that of Common Lisp, and that we're working on it. (Compatibility Issues): Reiterate the Common Lisp versus Emacs Lisp compatibility issues. (Comparison of Numbers, Arithmetic Operations): * lispref/commands.texi (Command Loop Info, Working With Events): * lispref/buffers.texi (Modification Time): Be more exact in describing where fixnums but not integers in general are accepted.
author Aidan Kehoe <kehoea@parhasard.net>
date Sun, 24 Jan 2010 15:21:27 +0000
parents 576fb035e263
children 755ae5b97edb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 438
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @c See the file lispref.texi for copying conditions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @setfilename ../../info/debugging.info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6 @node Debugging, Read and Print, Byte Compilation, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @chapter Debugging Lisp Programs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 There are three ways to investigate a problem in an XEmacs Lisp program,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
10 depending on what you are doing with the program when the problem appears.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
14 If the problem occurs when you run the program, you can use a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15 debugger (either the default debugger or Edebug) to investigate what is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16 happening during execution.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19 If the problem is syntactic, so that Lisp cannot even read the program,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 you can use the XEmacs facilities for editing Lisp to localize it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23 If the problem occurs when trying to compile the program with the byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 compiler, you need to know how to examine the compiler's input buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28 * Debugger:: How the XEmacs Lisp debugger is implemented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 * Syntax Errors:: How to find syntax errors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 * Compilation Errors:: How to find errors that show up in byte compilation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 * Edebug:: A source-level XEmacs Lisp debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
33
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34 Another useful debugging tool is the dribble file. When a dribble
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35 file is open, XEmacs copies all keyboard input characters to that file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36 Afterward, you can examine the file to find out what input was used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 @xref{Terminal Input}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39 For debugging problems in terminal descriptions, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40 @code{open-termscript} function can be useful. @xref{Terminal Output}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 @node Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 @section The Lisp Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 @cindex debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 @cindex Lisp debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46 @cindex break
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 The @dfn{Lisp debugger} provides the ability to suspend evaluation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 a form. While evaluation is suspended (a state that is commonly known
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 as a @dfn{break}), you may examine the run time stack, examine the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51 values of local or global variables, or change those values. Since a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52 break is a recursive edit, all the usual editing facilities of XEmacs are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53 available; you can even run programs that will enter the debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54 recursively. @xref{Recursive Editing}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57 * Error Debugging:: Entering the debugger when an error happens.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 * Infinite Loops:: Stopping and debugging a program that doesn't exit.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 * Function Debugging:: Entering it when a certain function is called.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60 * Explicit Debug:: Entering it at a certain point in the program.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 * Using Debugger:: What the debugger does; what you see while in it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62 * Debugger Commands:: Commands used while in the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63 * Invoking the Debugger:: How to call the function @code{debug}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 * Internals of Debugger:: Subroutines of the debugger, and global variables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
66
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67 @node Error Debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 @subsection Entering the Debugger on an Error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69 @cindex error debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70 @cindex debugging errors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
72 The most important time to enter the debugger is when a Lisp error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73 happens. This allows you to investigate the immediate causes of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 However, entry to the debugger is not a normal consequence of an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77 error. Many commands frequently get Lisp errors when invoked in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 during ordinary editing it would be very unpleasant to enter the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 debugger each time this happens. If you want errors to enter the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81 debugger, set the variable @code{debug-on-error} to non-@code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83 @defopt debug-on-error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 This variable determines whether the debugger is called when an error is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85 signaled and not handled. If @code{debug-on-error} is @code{t}, all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 errors call the debugger. If it is @code{nil}, none call the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 The value can also be a list of error conditions that should call the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 debugger. For example, if you set it to the list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 @code{(void-variable)}, then only errors about a variable that has no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91 value invoke the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 When this variable is non-@code{nil}, Emacs does not catch errors that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 happen in process filter functions and sentinels. Therefore, these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 errors also can invoke the debugger. @xref{Processes}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
97
438
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
98 @defopt debug-on-signal
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
99 This variable is similar to @code{debug-on-error} but breaks
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
100 whenever an error is signalled, regardless of whether it would be
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
101 handled.
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
102 @end defopt
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 428
diff changeset
103
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104 @defopt debug-ignored-errors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105 This variable specifies certain kinds of errors that should not enter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106 the debugger. Its value is a list of error condition symbols and/or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 regular expressions. If the error has any of those condition symbols,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108 or if the error message matches any of the regular expressions, then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 that error does not enter the debugger, regardless of the value of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110 @code{debug-on-error}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 The normal value of this variable lists several errors that happen often
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 during editing but rarely result from bugs in Lisp programs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 To debug an error that happens during loading of the @file{.emacs}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117 file, use the option @samp{-debug-init}, which binds
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 @code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119 inhibits use of @code{condition-case} to catch init file errors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121 If your @file{.emacs} file sets @code{debug-on-error}, the effect may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122 not last past the end of loading @file{.emacs}. (This is an undesirable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 byproduct of the code that implements the @samp{-debug-init} command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 line option.) The best way to make @file{.emacs} set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125 @code{debug-on-error} permanently is with @code{after-init-hook}, like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129 (add-hook 'after-init-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
130 '(lambda () (setq debug-on-error t)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
133 @node Infinite Loops
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
134 @subsection Debugging Infinite Loops
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
135 @cindex infinite loops
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
136 @cindex loops, infinite
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
137 @cindex quitting from infinite loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
138 @cindex stopping an infinite loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
140 When a program loops infinitely and fails to return, your first
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
141 problem is to stop the loop. On most operating systems, you can do this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
142 with @kbd{C-g}, which causes quit.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
143
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
144 Ordinary quitting gives no information about why the program was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
145 looping. To get more information, you can set the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
146 @code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
147 considered an error, and @code{debug-on-error} has no effect on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
148 handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
149 errors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
150
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
151 Once you have the debugger running in the middle of the infinite loop,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
152 you can proceed from the debugger using the stepping commands. If you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
153 step through the entire loop, you will probably get enough information
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
154 to solve the problem.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 @defopt debug-on-quit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
157 This variable determines whether the debugger is called when @code{quit}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
158 is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 then the debugger is called whenever you quit (that is, type @kbd{C-g}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160 If @code{debug-on-quit} is @code{nil}, then the debugger is not called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
161 when you quit. @xref{Quitting}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
162 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
163
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
164 @node Function Debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
165 @subsection Entering the Debugger on a Function Call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
166 @cindex function call debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
167 @cindex debugging specific functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
168
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169 To investigate a problem that happens in the middle of a program, one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170 useful technique is to enter the debugger whenever a certain function is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 called. You can do this to the function in which the problem occurs,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172 and then step through the function, or you can do this to a function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 called shortly before the problem, step quickly over the call to that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 function, and then step through its caller.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176 @deffn Command debug-on-entry function-name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 This function requests @var{function-name} to invoke the debugger each time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
178 it is called. It works by inserting the form @code{(debug 'debug)} into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179 the function definition as the first form.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 Any function defined as Lisp code may be set to break on entry,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182 regardless of whether it is interpreted code or compiled code. If the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183 function is a command, it will enter the debugger when called from Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184 and when called interactively (after the reading of the arguments). You
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185 can't debug primitive functions (i.e., those written in C) this way.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 When @code{debug-on-entry} is called interactively, it prompts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 for @var{function-name} in the minibuffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 If the function is already set up to invoke the debugger on entry,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191 @code{debug-on-entry} does nothing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193 @strong{Please note:} if you redefine a function after using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 @code{debug-on-entry} on it, the code to enter the debugger is lost.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196 @code{debug-on-entry} returns @var{function-name}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 (defun fact (n)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201 (if (zerop n) 1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
202 (* n (fact (1- n)))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
203 @result{} fact
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
204 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
205 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
206 (debug-on-entry 'fact)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
207 @result{} fact
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
208 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
209 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
210 (fact 3)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
211 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
212
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
213 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
214 ------ Buffer: *Backtrace* ------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
215 Entering:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
216 * fact(3)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
217 eval-region(4870 4878 t)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
218 byte-code("...")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
219 eval-last-sexp(nil)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
220 (let ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
221 eval-insert-last-sexp(nil)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
222 * call-interactively(eval-insert-last-sexp)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
223 ------ Buffer: *Backtrace* ------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
224 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
225
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
226 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
227 (symbol-function 'fact)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228 @result{} (lambda (n)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229 (debug (quote debug))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 (if (zerop n) 1 (* n (fact (1- n)))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 438
diff changeset
235 @deffn Command cancel-debug-on-entry &optional function-name
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 This function undoes the effect of @code{debug-on-entry} on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237 @var{function-name}. When called interactively, it prompts for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238 @var{function-name} in the minibuffer. If @var{function-name} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239 @code{nil} or the empty string, it cancels debugging for all functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241 If @code{cancel-debug-on-entry} is called more than once on the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 function, the second call does nothing. @code{cancel-debug-on-entry}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 returns @var{function-name}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 @node Explicit Debug
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247 @subsection Explicit Entry to the Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
249 You can cause the debugger to be called at a certain point in your
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 program by writing the expression @code{(debug)} at that point. To do
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251 this, visit the source file, insert the text @samp{(debug)} at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 proper place, and type @kbd{C-M-x}. Be sure to undo this insertion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253 before you save the file!
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255 The place where you insert @samp{(debug)} must be a place where an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 additional form can be evaluated and its value ignored. (If the value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 of @code{(debug)} isn't ignored, it will alter the execution of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258 program!) The most common suitable places are inside a @code{progn} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 an implicit @code{progn} (@pxref{Sequencing}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261 @node Using Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262 @subsection Using the Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
264 When the debugger is entered, it displays the previously selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
265 buffer in one window and a buffer named @samp{*Backtrace*} in another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
266 window. The backtrace buffer contains one line for each level of Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
267 function execution currently going on. At the beginning of this buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
268 is a message describing the reason that the debugger was invoked (such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
269 as the error message and associated data, if it was invoked due to an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
270 error).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
271
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
272 The backtrace buffer is read-only and uses a special major mode,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
273 Debugger mode, in which letters are defined as debugger commands. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
274 usual XEmacs editing commands are available; thus, you can switch windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
275 to examine the buffer that was being edited at the time of the error,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
276 switch buffers, visit files, or do any other sort of editing. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
277 the debugger is a recursive editing level (@pxref{Recursive Editing})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
278 and it is wise to go back to the backtrace buffer and exit the debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
279 (with the @kbd{q} command) when you are finished with it. Exiting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
280 the debugger gets out of the recursive edit and kills the backtrace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
281 buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
282
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
283 @cindex current stack frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
284 The backtrace buffer shows you the functions that are executing and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 their argument values. It also allows you to specify a stack frame by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286 moving point to the line describing that frame. (A stack frame is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287 place where the Lisp interpreter records information about a particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 invocation of a function.) The frame whose line point is on is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289 considered the @dfn{current frame}. Some of the debugger commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
290 operate on the current frame.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292 The debugger itself must be run byte-compiled, since it makes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293 assumptions about how many stack frames are used for the debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294 itself. These assumptions are false if the debugger is running
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 interpreted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
296
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297 @need 3000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299 @node Debugger Commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300 @subsection Debugger Commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 @cindex debugger command list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 Inside the debugger (in Debugger mode), these special commands are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
304 available in addition to the usual cursor motion commands. (Keep in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305 mind that all the usual facilities of XEmacs, such as switching windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306 or buffers, are still available.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
307
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308 The most important use of debugger commands is for stepping through
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309 code, so that you can see how control flows. The debugger can step
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 through the control structures of an interpreted function, but cannot do
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 so in a byte-compiled function. If you would like to step through a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
312 byte-compiled function, replace it with an interpreted definition of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
313 same function. (To do this, visit the source file for the function and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
314 type @kbd{C-M-x} on its definition.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 Here is a list of Debugger mode commands:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318 @table @kbd
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 @item c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 Exit the debugger and continue execution. This resumes execution of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 program as if the debugger had never been entered (aside from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322 effect of any variables or data structures you may have changed while
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323 inside the debugger).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325 Continuing when an error or quit was signalled will cause the normal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 action of the signalling to take place. If you do not want this to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327 happen, but instead want the program execution to continue as if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 the call to @code{signal} did not occur, use the @kbd{r} command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 @item d
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 Continue execution, but enter the debugger the next time any Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332 function is called. This allows you to step through the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333 subexpressions of an expression, seeing what values the subexpressions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 compute, and what else they do.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 The stack frame made for the function call which enters the debugger in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 this way will be flagged automatically so that the debugger will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338 called again when the frame is exited. You can use the @kbd{u} command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 to cancel this flag.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341 @item b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342 Flag the current frame so that the debugger will be entered when the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343 frame is exited. Frames flagged in this way are marked with stars
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 in the backtrace buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 @item u
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347 Don't enter the debugger when the current frame is exited. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348 cancels a @kbd{b} command on that frame.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
349
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 @item e
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
351 Read a Lisp expression in the minibuffer, evaluate it, and print the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352 value in the echo area. The debugger alters certain important
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 variables, and the current buffer, as part of its operation; @kbd{e}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354 temporarily restores their outside-the-debugger values so you can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355 examine them. This makes the debugger more transparent. By contrast,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 @kbd{M-:} does nothing special in the debugger; it shows you the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357 variable values within the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 @item q
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 Terminate the program being debugged; return to top-level XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361 command execution.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 If the debugger was entered due to a @kbd{C-g} but you really want
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364 to quit, and not debug, use the @kbd{q} command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
366 @item r
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367 Return a value from the debugger. The value is computed by reading an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 expression with the minibuffer and evaluating it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
370 The @kbd{r} command is useful when the debugger was invoked due to exit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
371 from a Lisp call frame (as requested with @kbd{b}); then the value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 specified in the @kbd{r} command is used as the value of that frame. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373 is also useful if you call @code{debug} and use its return value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
375 If the debugger was entered at the beginning of a function call, @kbd{r}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
376 has the same effect as @kbd{c}, and the specified return value does not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377 matter.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
378
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379 If the debugger was entered through a call to @code{signal} (i.e. as a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380 result of an error or quit), then returning a value will cause the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381 call to @code{signal} itself to return, rather than throwing to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 top-level or invoking a handler, as is normal. This allows you to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 correct an error (e.g. the type of an argument was wrong) or continue
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384 from a @code{debug-on-quit} as if it never happened.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 Note that some errors (e.g. any error signalled using the @code{error}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
387 function, and many errors signalled from a primitive function) are not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
388 continuable. If you return a value from them and continue execution,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
389 then the error will immediately be signalled again. Other errors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
390 (e.g. wrong-type-argument errors) will be continually resignalled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
391 until the problem is corrected.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
392 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
394 @node Invoking the Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
395 @subsection Invoking the Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
397 Here we describe fully the function used to invoke the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
398
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
399 @defun debug &rest debugger-args
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
400 This function enters the debugger. It switches buffers to a buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
401 named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
402 recursive entry to the debugger, etc.), and fills it with information
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
403 about the stack of Lisp function calls. It then enters a recursive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 edit, showing the backtrace buffer in Debugger mode.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406 The Debugger mode @kbd{c} and @kbd{r} commands exit the recursive edit;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
407 then @code{debug} switches back to the previous buffer and returns to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
408 whatever called @code{debug}. This is the only way the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
409 @code{debug} can return to its caller.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
410
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
411 If the first of the @var{debugger-args} passed to @code{debug} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
412 @code{nil} (or if it is not one of the special values in the table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413 below), then @code{debug} displays the rest of its arguments at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
414 top of the @samp{*Backtrace*} buffer. This mechanism is used to display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415 a message to the user.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
416
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417 However, if the first argument passed to @code{debug} is one of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
418 following special values, then it has special significance. Normally,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
419 these values are passed to @code{debug} only by the internals of XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 and the debugger, and not by programmers calling @code{debug}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422 The special values are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
425 @item lambda
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
426 @cindex @code{lambda} in debug
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 A first argument of @code{lambda} means @code{debug} was called because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428 of entry to a function when @code{debug-on-next-call} was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
429 non-@code{nil}. The debugger displays @samp{Entering:} as a line of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
430 text at the top of the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
432 @item debug
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
433 @code{debug} as first argument indicates a call to @code{debug} because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 of entry to a function that was set to debug on entry. The debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435 displays @samp{Entering:}, just as in the @code{lambda} case. It also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436 marks the stack frame for that function so that it will invoke the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 debugger when exited.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439 @item t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
440 When the first argument is @code{t}, this indicates a call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 @code{debug} due to evaluation of a list form when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 @code{debug-on-next-call} is non-@code{nil}. The debugger displays the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443 following as the top line in the buffer:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446 Beginning evaluation of function call form:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 @item exit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
450 When the first argument is @code{exit}, it indicates the exit of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451 stack frame previously marked to invoke the debugger on exit. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452 second argument given to @code{debug} in this case is the value being
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 returned from the frame. The debugger displays @samp{Return value:} on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 the top line of the buffer, followed by the value being returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 @item error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457 @cindex @code{error} in debug
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458 When the first argument is @code{error}, the debugger indicates that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 it is being entered because an error or @code{quit} was signaled and not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460 handled, by displaying @samp{Signaling:} followed by the error signaled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
461 and any arguments to @code{signal}. For example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
462
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
463 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
464 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465 (let ((debug-on-error t))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 (/ 1 0))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470 ------ Buffer: *Backtrace* ------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
471 Signaling: (arith-error)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 /(1 0)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 ------ Buffer: *Backtrace* ------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
475 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478 If an error was signaled, presumably the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
479 @code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 then presumably the variable @code{debug-on-quit} is non-@code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482 @item nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483 Use @code{nil} as the first of the @var{debugger-args} when you want
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 to enter the debugger explicitly. The rest of the @var{debugger-args}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485 are printed on the top line of the buffer. You can use this feature to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486 display messages---for example, to remind yourself of the conditions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487 under which @code{debug} is called.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
490
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
491 @need 5000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
492
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493 @node Internals of Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494 @subsection Internals of the Debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
496 This section describes functions and variables used internally by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
497 debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
498
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
499 @defvar debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
500 The value of this variable is the function to call to invoke the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
501 debugger. Its value must be a function of any number of arguments (or,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
502 more typically, the name of a function). Presumably this function will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
503 enter some kind of debugger. The default value of the variable is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
504 @code{debug}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
505
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
506 The first argument that Lisp hands to the function indicates why it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
507 was called. The convention for arguments is detailed in the description
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
508 of @code{debug}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
509 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
510
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
511 @deffn Command backtrace &optional stream detailed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
512 @cindex run time stack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
513 @cindex call stack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
514 This function prints a trace of Lisp function calls currently active.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
515 This is the function used by @code{debug} to fill up the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
516 @samp{*Backtrace*} buffer. It is written in C, since it must have access
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
517 to the stack to determine which function calls are active. The return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
518 value is always @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
519
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
520 The backtrace is normally printed to @code{standard-output}, but this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
521 can be changed by specifying a value for @var{stream}. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
522 @var{detailed} is non-@code{nil}, the backtrace also shows places where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
523 currently active variable bindings, catches, condition-cases, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
524 unwind-protects were made as well as function calls.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
525
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
526 In the following example, a Lisp expression calls @code{backtrace}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
527 explicitly. This prints the backtrace to the stream
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
528 @code{standard-output}: in this case, to the buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
529 @samp{backtrace-output}. Each line of the backtrace represents one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
530 function call. The line shows the values of the function's arguments if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
531 they are all known. If they are still being computed, the line says so.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
532 The arguments of special forms are elided.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
533
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
534 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
535 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
536 (with-output-to-temp-buffer "backtrace-output"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
537 (let ((var 1))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
538 (save-excursion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
539 (setq var (eval '(progn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
540 (1+ var)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
541 (list 'testing (backtrace))))))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
542
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
543 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
544 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
545
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
546 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
547 ----------- Buffer: backtrace-output ------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
548 backtrace()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
549 (list ...computing arguments...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
550 (progn ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
551 eval((progn (1+ var) (list (quote testing) (backtrace))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
552 (setq ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
553 (save-excursion ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
554 (let ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
555 (with-output-to-temp-buffer ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
556 eval-region(1973 2142 #<buffer *scratch*>)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
557 byte-code("... for eval-print-last-sexp ...")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
558 eval-print-last-sexp(nil)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
559 * call-interactively(eval-print-last-sexp)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
560 ----------- Buffer: backtrace-output ------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
561 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
562 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
563
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
564 The character @samp{*} indicates a frame whose debug-on-exit flag is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
565 set.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
566 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
567
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
568 @ignore @c Not worth mentioning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
569 @defopt stack-trace-on-error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
570 @cindex stack trace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
571 This variable controls whether Lisp automatically displays a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
572 backtrace buffer after every error that is not handled. A quit signal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
573 counts as an error for this variable. If it is non-@code{nil} then a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
574 backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
575 error. If it is @code{nil}, then a backtrace is not shown.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
576
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
577 When a backtrace is shown, that buffer is not selected. If either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
578 @code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
579 a backtrace is shown in one buffer, and the debugger is popped up in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
580 another buffer with its own backtrace.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
581
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
582 We consider this feature to be obsolete and superseded by the debugger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
583 itself.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
584 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
585 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
586
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
587 @defvar debug-on-next-call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
588 @cindex @code{eval}, and debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
589 @cindex @code{apply}, and debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
590 @cindex @code{funcall}, and debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
591 If this variable is non-@code{nil}, it says to call the debugger before
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
592 the next @code{eval}, @code{apply} or @code{funcall}. Entering the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
593 debugger sets @code{debug-on-next-call} to @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
594
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
595 The @kbd{d} command in the debugger works by setting this variable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
596 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
597
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
598 @defun backtrace-debug level flag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
599 This function sets the debug-on-exit flag of the stack frame @var{level}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
600 levels down the stack, giving it the value @var{flag}. If @var{flag} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
601 non-@code{nil}, this will cause the debugger to be entered when that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
602 frame later exits. Even a nonlocal exit through that frame will enter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
603 the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
605 This function is used only by the debugger.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
606 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
607
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
608 @defvar command-debug-status
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
609 This variable records the debugging status of the current interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
610 command. Each time a command is called interactively, this variable is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
611 bound to @code{nil}. The debugger can set this variable to leave
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
612 information for future debugger invocations during the same command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
613
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
614 The advantage, for the debugger, of using this variable rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
615 another global variable is that the data will never carry over to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
616 subsequent command invocation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
617 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
618
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
619 @defun backtrace-frame frame-number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
620 The function @code{backtrace-frame} is intended for use in Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
621 debuggers. It returns information about what computation is happening
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
622 in the stack frame @var{frame-number} levels down.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
624 If that frame has not evaluated the arguments yet (or is a special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
625 form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
626
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
627 If that frame has evaluated its arguments and called its function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
628 already, the value is @code{(t @var{function}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
629 @var{arg-values}@dots{})}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
630
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
631 In the return value, @var{function} is whatever was supplied as the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
632 @sc{car} of the evaluated list, or a @code{lambda} expression in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
633 case of a macro call. If the function has a @code{&rest} argument, that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
634 is represented as the tail of the list @var{arg-values}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
635
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
636 If @var{frame-number} is out of range, @code{backtrace-frame} returns
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
637 @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
638 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
639
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
640 @node Syntax Errors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
641 @section Debugging Invalid Lisp Syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
642
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
643 The Lisp reader reports invalid syntax, but cannot say where the real
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
644 problem is. For example, the error ``End of file during parsing'' in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
645 evaluating an expression indicates an excess of open parentheses (or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
646 square brackets). The reader detects this imbalance at the end of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
647 file, but it cannot figure out where the close parenthesis should have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
648 been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
649 parenthesis or missing open parenthesis, but does not say where the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
650 missing parenthesis belongs. How, then, to find what to change?
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
651
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
652 If the problem is not simply an imbalance of parentheses, a useful
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
653 technique is to try @kbd{C-M-e} at the beginning of each defun, and see
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
654 if it goes to the place where that defun appears to end. If it does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
655 not, there is a problem in that defun.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
656
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
657 However, unmatched parentheses are the most common syntax errors in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
658 Lisp, and we can give further advice for those cases.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
659
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
660 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
661 * Excess Open:: How to find a spurious open paren or missing close.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
662 * Excess Close:: How to find a spurious close paren or missing open.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
663 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
664
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
665 @node Excess Open
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
666 @subsection Excess Open Parentheses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
667
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
668 The first step is to find the defun that is unbalanced. If there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
669 an excess open parenthesis, the way to do this is to insert a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
670 close parenthesis at the end of the file and type @kbd{C-M-b}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
671 (@code{backward-sexp}). This will move you to the beginning of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
672 defun that is unbalanced. (Then type @kbd{C-@key{SPC} C-_ C-u
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
673 C-@key{SPC}} to set the mark there, undo the insertion of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
674 close parenthesis, and finally return to the mark.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
675
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
676 The next step is to determine precisely what is wrong. There is no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
677 way to be sure of this except to study the program, but often the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
678 existing indentation is a clue to where the parentheses should have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
679 been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
680 and see what moves.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
681
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
682 Before you do this, make sure the defun has enough close parentheses.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
683 Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
684 of the file until the end. So move to the end of the defun and insert a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
685 close parenthesis there. Don't use @kbd{C-M-e} to move there, since
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
686 that too will fail to work until the defun is balanced.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
687
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
688 Now you can go to the beginning of the defun and type @kbd{C-M-q}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
689 Usually all the lines from a certain point to the end of the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
690 will shift to the right. There is probably a missing close parenthesis,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
691 or a superfluous open parenthesis, near that point. (However, don't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
692 assume this is true; study the code to make sure.) Once you have found
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
693 the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
694 indentation is probably appropriate to the intended parentheses.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
695
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
696 After you think you have fixed the problem, use @kbd{C-M-q} again. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
697 the old indentation actually fit the intended nesting of parentheses,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
698 and you have put back those parentheses, @kbd{C-M-q} should not change
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
699 anything.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
700
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
701 @node Excess Close
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
702 @subsection Excess Close Parentheses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
703
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
704 To deal with an excess close parenthesis, first insert an open
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
705 parenthesis at the beginning of the file, back up over it, and type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
706 @kbd{C-M-f} to find the end of the unbalanced defun. (Then type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
707 @kbd{C-@key{SPC} C-_ C-u C-@key{SPC}} to set the mark there, undo the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
708 insertion of the open parenthesis, and finally return to the mark.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
709
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
710 Then find the actual matching close parenthesis by typing @kbd{C-M-f}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
711 at the beginning of the defun. This will leave you somewhere short of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
712 the place where the defun ought to end. It is possible that you will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
713 find a spurious close parenthesis in that vicinity.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
714
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
715 If you don't see a problem at that point, the next thing to do is to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
716 type @kbd{C-M-q} at the beginning of the defun. A range of lines will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
717 probably shift left; if so, the missing open parenthesis or spurious
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
718 close parenthesis is probably near the first of those lines. (However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
719 don't assume this is true; study the code to make sure.) Once you have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
720 found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
721 old indentation is probably appropriate to the intended parentheses.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
722
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
723 After you think you have fixed the problem, use @kbd{C-M-q} again. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
724 the old indentation actually fit the intended nesting of parentheses,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
725 and you have put back those parentheses, @kbd{C-M-q} should not change
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
726 anything.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
727
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
728 @node Compilation Errors, Edebug, Syntax Errors, Debugging
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
729 @section Debugging Problems in Compilation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
730
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
731 When an error happens during byte compilation, it is normally due to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
732 invalid syntax in the program you are compiling. The compiler prints a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
733 suitable error message in the @samp{*Compile-Log*} buffer, and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
734 stops. The message may state a function name in which the error was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
735 found, or it may not. Either way, here is how to find out where in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
736 file the error occurred.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
738 What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
739 (Note that the buffer name starts with a space, so it does not show
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
740 up in @kbd{M-x list-buffers}.) This buffer contains the program being
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
741 compiled, and point shows how far the byte compiler was able to read.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
742
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
743 If the error was due to invalid Lisp syntax, point shows exactly where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
744 the invalid syntax was @emph{detected}. The cause of the error is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
745 necessarily near by! Use the techniques in the previous section to find
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
746 the error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
747
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
748 If the error was detected while compiling a form that had been read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
749 successfully, then point is located at the end of the form. In this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
750 case, this technique can't localize the error precisely, but can still
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
751 show you which function to check.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
752
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
753 @include edebug-inc.texi