New file.

[bpt/emacs.git] / etc / DEBUG

diff --git a/etc/DEBUG b/etc/DEBUG
index 7ae4ab9..eb2a336 100644 (file)
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -16,13 +16,17 @@ Copyright (c) 1985, 2000, 2001 Free Software Foundation, Inc.
 should read the Windows-specific section near the end of this
 document.]
 
-It is a good idea to run Emacs under GDB (or some other suitable
+** When you debug Emacs with GDB, you should start it in the directory
+where you built Emacs.  That directory has a .gdbinit file that defines
+various "user-defined" commands for debugging Emacs.
+
+** It is a good idea to run Emacs under GDB (or some other suitable
 debugger) *all the time*.  Then, when Emacs crashes, you will be able
 to debug the live process, not just a core dump.  (This is especially
 important on systems which don't support core files, and instead print
 just the registers and some stack addresses.)
 
-If Emacs hangs, or seems to be stuck in some infinite loop, typing
+** If Emacs hangs, or seems to be stuck in some infinite loop, typing
 "kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to
 kick in, provided that you run under GDB.
 
@@ -32,7 +36,7 @@ kick in, provided that you run under GDB.
 All Lisp errors go through there.
 
 It is useful, when debugging, to have a guaranteed way to return to
-the debugger at any time.  When using X, this is easy: type C-c at the
+the debugger at any time.  When using X, this is easy: type C-z at the
 window where Emacs is running under GDB, and it will stop Emacs just
 as it would stop any ordinary program.  When Emacs is running in a
 terminal, things are not so easy.
@@ -111,7 +115,7 @@ First, use these commands:
     cd src
     gdb emacs
     b xmenu.c:1296
-    r -q 
+    r -q
 
 Then type C-x 5 2 to create a new frame, and it hits the breakpoint:
 
@@ -124,9 +128,9 @@ Then type C-x 5 2 to create a new frame, and it hits the breakpoint:
     $2 = (struct frame *) 0x3f0800
     (gdb) p *$
     $3 = {
-      size = 536871989, 
-      next = 0x366240, 
-      name = 809661752, 
+      size = 536871989,
+      next = 0x366240,
+      name = 809661752,
       [...]
     }
     (gdb) p $3->name
@@ -173,7 +177,7 @@ this vector.  `recent_keys' is updated in keyboard.c by the command
   XVECTOR (recent_keys)->contents[recent_keys_index] = c;
 
 So we define a GDB command `xvector-elts', so the last 10 keystrokes
-are printed by 
+are printed by
 
     xvector-elts recent_keys recent_keys_index 10
 
@@ -185,7 +189,7 @@ where you can define xvector-elts as follows:
     xvector
     set $foo = $
     while $i < $arg2
-    p $foo->contents[$arg1-($i++)] 
+    p $foo->contents[$arg1-($i++)]
     pr
     end
     document xvector-elts
@@ -213,7 +217,7 @@ of function calling.
 
 By printing the remaining elements of args, you can see the argument
 values.  Here's how to print the first argument:
-  
+
    p args[1]
    pr
 
@@ -226,7 +230,7 @@ conveniently.  For example:
 
 and, assuming that "xtype" says that args[0] is a symbol:
 
-   xsymbol 
+   xsymbol
 
 ** Debugging what happens while preloading and dumping Emacs
 
@@ -301,6 +305,19 @@ procedure:
   - You should now look around this offending X call and try to figure
     out what is wrong with it.
 
+** If Emacs causes errors or memory leaks in your X server
+
+You can trace the traffic between Emacs and your X server with a tool
+like xmon, available at ftp://ftp.x.org/contrib/devel_tools/.
+
+Xmon can be used to see exactly what Emacs sends when X protocol errors
+happen.  If Emacs causes the X server memory usage to increase you can
+use xmon to see what items Emacs creates in the server (windows,
+graphical contexts, pixmaps) and what items Emacs delete.  If there
+are consistently more creations than deletions, the type of item
+and the activity you do when the items get created can give a hint where
+to start debugging.
+
 ** If the symptom of the bug is that Emacs fails to respond
 
 Don't assume Emacs is `hung'--it may instead be in an infinite loop.
@@ -433,7 +450,7 @@ and keyboard events, or LessTif menus behave weirdly, it might be
 helpful to set the `DEBUGSOURCES' and `DEBUG_FILE' environment
 variables, so that one can see what LessTif was doing at this point.
 For instance
-  
+
   export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
   export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
   emacs &