0
+ − 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.