annotate doc/lispref/debugging.texi @ 99043:ef3e520abfd6

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