etc/DEBUG

   1 Debugging GNU Emacs
   2 Copyright (c) 1985, 2000 Free Software Foundation, Inc.
   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 ** Some useful techniques
  16
  17 `Fsignal' is a very useful place to stop in.
  18 All Lisp errors go through there.
  19
  20 It is useful, when debugging, to have a guaranteed way
  21 to return to the debugger at any time.  If you are using
  22 interrupt-driven input, which is the default, then Emacs is using
  23 RAW mode and the only way you can do it is to store
  24 the code for some character into the variable stop_character:
  25
  26     set stop_character = 29
  27
  28 makes Control-] (decimal code 29) the stop character.
  29 Typing Control-] will cause immediate stop.  You cannot
  30 use the set command until the inferior process has been started.
  31 Put a breakpoint early in `main', or suspend the Emacs,
  32 to get an opportunity to do the set command.
  33
  34 If you are using cbreak input (see the Lisp function set-input-mode),
  35 then typing Control-g will cause a SIGINT, which will return control
  36 to GDB immediately if you type this command first:
  37
  38     handle 2 stop
  39
  40
  41 ** Examining Lisp object values.
  42
  43 When you have a live process to debug, and it has not encountered a
  44 fatal error, you can use the GDB command `pr'.  First print the value
  45 in the ordinary way, with the `p' command.  Then type `pr' with no
  46 arguments.  This calls a subroutine which uses the Lisp printer.
  47
  48 If you can't use this command, either because the process can't run
  49 a subroutine or because the data is invalid, you can fall back on
  50 lower-level commands.
  51
  52 Use the `xtype' command to print out the data type of the last data
  53 value.  Once you know the data type, use the command that corresponds
  54 to that type.  Here are these commands:
  55
  56     xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
  57     xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
  58     xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
  59
  60 Each one of them applies to a certain type or class of types.
  61 (Some of these types are not visible in Lisp, because they exist only
  62 internally.)
  63
  64 Each x... command prints some information about the value, and
  65 produces a GDB value (subsequently available in $) through which you
  66 can get at the rest of the contents.
  67
  68 In general, most of the rest of the contents will be addition Lisp
  69 objects which you can examine in turn with the x... commands.
  70
  71 ** If GDB does not run and your debuggers can't load Emacs.
  72
  73 On some systems, no debugger can load Emacs with a symbol table,
  74 perhaps because they all have fixed limits on the number of symbols
  75 and Emacs exceeds the limits.  Here is a method that can be used
  76 in such an extremity.  Do
  77
  78     nm -n temacs > nmout
  79     strip temacs
  80     adb temacs
  81     0xd:i
  82     0xe:i
  83     14:i
  84     17:i
  85     :r -l loadup   (or whatever)
  86
  87 It is necessary to refer to the file `nmout' to convert
  88 numeric addresses into symbols and vice versa.
  89
  90 It is useful to be running under a window system.
  91 Then, if Emacs becomes hopelessly wedged, you can create
  92 another window to do kill -9 in.  kill -ILL is often
  93 useful too, since that may make Emacs dump core or return
  94 to adb.
  95
  96
  97 ** Debugging incorrect screen updating.
  98
  99 To debug Emacs problems that update the screen wrong, it is useful
 100 to have a record of what input you typed and what Emacs sent to the
 101 screen.  To make these records, do
 102
 103 (open-dribble-file "~/.dribble")
 104 (open-termscript "~/.termscript")
 105
 106 The dribble file contains all characters read by Emacs from the
 107 terminal, and the termscript file contains all characters it sent to
 108 the terminal.  The use of the directory `~/' prevents interference
 109 with any other user.
 110
 111 If you have irreproducible display problems, put those two expressions
 112 in your ~/.emacs file.  When the problem happens, exit the Emacs that
 113 you were running, kill it, and rename the two files.  Then you can start
 114 another Emacs without clobbering those files, and use it to examine them.
 115
 116 An easy way to see if too much text is being redrawn on a terminal is to
 117 evaluate `(setq inverse-video t)' before you try the operation you think
 118 will cause too much redrawing.  This doesn't refresh the screen, so only
 119 newly drawn text is in inverse video.