| 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. |