#

1 files changed, 143 insertions, 0 deletions

diff --git a/etc/DEBUG b/etc/DEBUG
new file mode 100644
index 00000000000..045444d11ae
--- /dev/null
+++ b/etc/DEBUG
@@ -0,0 +1,143 @@
+Debugging GNU Emacs
+Copyright (c) 1985 Richard M. Stallman.
+
+   Permission is granted to anyone to make or distribute verbatim copies
+   of this document as received, in any medium, provided that the
+   copyright notice and permission notice are preserved,
+   and that the distributor grants the recipient permission
+   for further redistribution as permitted by this notice.
+
+   Permission is granted to distribute modified versions
+   of this document, or of portions of it,
+   under the above conditions, provided also that they
+   carry prominent notices stating who last changed them.
+
+On 4.2 you will probably find that dbx does not work for
+debugging GNU Emacs.  For one thing, dbx does not keep the
+inferior process's terminal modes separate from its own.
+For another, dbx does not put the inferior in a separate
+process group, which makes trouble when an inferior uses
+interrupt input, which GNU Emacs must do on 4.2.
+
+dbx has also been observed to have other problems,
+such as getting incorrect values for register variables
+in stack frames other than the innermost one.
+
+The Emacs distribution now contains GDB, the new source-level
+debugger for the GNU system.  GDB works for debugging Emacs.
+GDB currently runs on vaxes under 4.2 and on Sun 2 and Sun 3
+systems.
+
+
+** Some useful techniques
+
+`Fsignal' is a very useful place to stop in.
+All Lisp errors go through there.
+
+It is useful, when debugging, to have a guaranteed way
+to return to the debugger at any time.  If you are using
+interrupt-driven input, which is the default, then Emacs is using
+RAW mode and the only way you can do it is to store
+the code for some character into the variable stop_character:
+
+    set stop_character = 29
+
+makes Control-] (decimal code 29) the stop character.
+Typing Control-] will cause immediate stop.  You cannot
+use the set command until the inferior process has been started.
+Put a breakpoint early in `main', or suspend the Emacs,
+to get an opportunity to do the set command.
+
+If you are using cbreak input (see the Lisp function set-input-mode),
+then typing Control-g will cause a SIGINT, which will return control
+to the debugger immediately unless you have done
+
+    ignore 3  (in dbx)
+or  handle 3 nostop noprint  (in gdb)
+
+You will note that most of GNU Emacs is written to avoid
+declaring a local variable in an inner block, even in
+cases where using one would be the cleanest thing to do.
+This is because dbx cannot access any of the variables
+in a function which has even one variable defined in an
+inner block.  A few functions in GNU Emacs do have variables
+in inner blocks, only because I wrote them before realizing
+that dbx had this problem and never rewrote them to avoid it.
+
+I believe that GDB does not have such a problem.
+
+
+** Examining Lisp object values.
+
+When you have a live process to debug, and it has not encountered a
+fatal error, you can use the GDB command `pr'.  First print the value
+in the ordinary way, with the `p' command.  Then type `pr' with no
+arguments.  This calls a subroutine which uses the Lisp printer.
+
+If you can't use this command, either because the process can't run
+a subroutine or because the data is invalid, you can fall back on
+lower-level commands.
+
+Use the `xtype' command to print out the data type of the last data
+value.  Once you know the data type, use the command that corresponds
+to that type.  Here are these commands:
+
+    xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
+    xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
+    xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
+
+Each one of them applies to a certain type or class of types.
+(Some of these types are not visible in Lisp, because they exist only
+internally.)
+
+Each x... command prints some information about the value, and
+produces a GDB value (subsequently available in $) through which you
+can get at the rest of the contents.
+
+In general, most of the rest of the contents will be addition Lisp
+objects which you can examine in turn with the x... commands.
+
+** If GDB does not run and your debuggers can't load Emacs.
+
+On some systems, no debugger can load Emacs with a symbol table,
+perhaps because they all have fixed limits on the number of symbols
+and Emacs exceeds the limits.  Here is a method that can be used
+in such an extremity.  Do
+
+    nm -n temacs > nmout
+    strip temacs
+    adb temacs
+    0xd:i
+    0xe:i
+    14:i
+    17:i
+    :r -l loadup   (or whatever)
+
+It is necessary to refer to the file `nmout' to convert
+numeric addresses into symbols and vice versa.
+
+It is useful to be running under a window system.
+Then, if Emacs becomes hopelessly wedged, you can create
+another window to do kill -9 in.  kill -ILL is often
+useful too, since that may make Emacs dump core or return
+to adb.
+
+
+** Debugging incorrect screen updating.
+
+To debug Emacs problems that update the screen wrong, it is useful
+to have a record of what input you typed and what Emacs sent to the
+screen.  To make these records, do
+
+(open-dribble-file "~/.dribble")
+(open-termscript "~/.termscript")
+
+The dribble file contains all characters read by Emacs from the
+terminal, and the termscript file contains all characters it sent to
+the terminal.  The use of the directory `~/' prevents interference
+with any other user.
+
+If you have irreproducible display problems, put those two expressions
+in your ~/.emacs file.  When the problem happens, exit the Emacs that
+you were running, kill it, and rename the two files.  Then you can start
+another Emacs without clobbering those files, and use it to examine them.