Mercurial > hg > xemacs-beta

comparison etc/DEBUG @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 Debugging GNU Emacs
2 Copyright (c) 1985 Richard M. Stallman.
3
4 Permission is granted to anyone to make or distribute verbatim copies
5 of this document as received, in any medium, provided that the
6 copyright notice and permission notice are preserved,
7 and that the distributor grants the recipient permission
8 for further redistribution as permitted by this notice.
9
10 Permission is granted to distribute modified versions
11 of this document, or of portions of it,
12 under the above conditions, provided also that they
13 carry prominent notices stating who last changed them.
14
15 On 4.2 you will probably find that dbx does not work for
16 debugging GNU Emacs. For one thing, dbx does not keep the
17 inferior process's terminal modes separate from its own.
18 For another, dbx does not put the inferior in a separate
19 process group, which makes trouble when an inferior uses
20 interrupt input, which GNU Emacs must do on 4.2.
21
22 dbx has also been observed to have other problems,
23 such as getting incorrect values for register variables
24 in stack frames other than the innermost one.
25
26 The Emacs distribution now contains GDB, the new source-level
27 debugger for the GNU system. GDB works for debugging Emacs.
28 GDB currently runs on vaxes under 4.2 and on Sun 2 and Sun 3
29 systems.
30
31
32 ** Some useful techniques
33
34 `Fsignal' is a very useful place to stop in.
35 All Lisp errors go through there.
36
37 It is useful, when debugging, to have a guaranteed way
38 to return to the debugger at any time. If you are using
39 interrupt-driven input, which is the default, then Emacs is using
40 RAW mode and the only way you can do it is to store
41 the code for some character into the variable stop_character:
42
43 set stop_character = 29
44
45 makes Control-] (decimal code 29) the stop character.
46 Typing Control-] will cause immediate stop. You cannot
47 use the set command until the inferior process has been started.
48 Put a breakpoint early in `main', or suspend the Emacs,
49 to get an opportunity to do the set command.
50
51 If you are using cbreak input (see the Lisp function set-input-mode),
52 then typing Control-g will cause a SIGINT, which will return control
53 to the debugger immediately unless you have done
54
55 ignore 3 (in dbx)
56 or handle 3 nostop noprint (in gdb)
57
58 You will note that most of GNU Emacs is written to avoid
59 declaring a local variable in an inner block, even in
60 cases where using one would be the cleanest thing to do.
61 This is because dbx cannot access any of the variables
62 in a function which has even one variable defined in an
63 inner block. A few functions in GNU Emacs do have variables
64 in inner blocks, only because I wrote them before realizing
65 that dbx had this problem and never rewrote them to avoid it.
66
67 I believe that GDB does not have such a problem.
68
69
70 ** Examining Lisp object values.
71
72 When you have a live process to debug, and it has not encountered a
73 fatal error, you can use the GDB command `pr'. First print the value
74 in the ordinary way, with the `p' command. Then type `pr' with no
75 arguments. This calls a subroutine which uses the Lisp printer.
76
77 If you can't use this command, either because the process can't run
78 a subroutine or because the data is invalid, you can fall back on
79 lower-level commands.
80
81 Use the `xtype' command to print out the data type of the last data
82 value. Once you know the data type, use the command that corresponds
83 to that type. Here are these commands:
84
85 xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
86 xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
87 xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
88
89 Each one of them applies to a certain type or class of types.
90 (Some of these types are not visible in Lisp, because they exist only
91 internally.)
92
93 Each x... command prints some information about the value, and
94 produces a GDB value (subsequently available in $) through which you
95 can get at the rest of the contents.
96
97 In general, most of the rest of the contents will be addition Lisp
98 objects which you can examine in turn with the x... commands.
99
100 ** If GDB does not run and your debuggers can't load Emacs.
101
102 On some systems, no debugger can load Emacs with a symbol table,
103 perhaps because they all have fixed limits on the number of symbols
104 and Emacs exceeds the limits. Here is a method that can be used
105 in such an extremity. Do
106
107 nm -n temacs > nmout
108 strip temacs
109 adb temacs
110 0xd:i
111 0xe:i
112 14:i
113 17:i
114 :r -l loadup (or whatever)
115
116 It is necessary to refer to the file `nmout' to convert
117 numeric addresses into symbols and vice versa.
118
119 It is useful to be running under a window system.
120 Then, if Emacs becomes hopelessly wedged, you can create
121 another window to do kill -9 in. kill -ILL is often
122 useful too, since that may make Emacs dump core or return
123 to adb.
124
125
126 ** Debugging incorrect screen updating.
127
128 To debug Emacs problems that update the screen wrong, it is useful
129 to have a record of what input you typed and what Emacs sent to the
130 screen. To make these records, do
131
132 (open-dribble-file "~/.dribble")
133 (open-termscript "~/.termscript")
134
135 The dribble file contains all characters read by Emacs from the
136 terminal, and the termscript file contains all characters it sent to
137 the terminal. The use of the directory `~/' prevents interference
138 with any other user.
139
140 If you have irreproducible display problems, put those two expressions
141 in your ~/.emacs file. When the problem happens, exit the Emacs that
142 you were running, kill it, and rename the two files. Then you can start
143 another Emacs without clobbering those files, and use it to examine them.