Commit | Line | Data |
---|---|---|
a933dad1 DL |
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. |