declare smobs in alloc.c

[bpt/emacs.git] / etc / DEBUG

diff --git a/etc/DEBUG b/etc/DEBUG
index 2604b39..c1b04ea 100644 (file)
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -1,7 +1,6 @@
 Debugging GNU Emacs
 
-Copyright (C) 1985, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
-  2008, 2009, 2010, 2011  Free Software Foundation, Inc.
+Copyright (C) 1985, 2000-2014 Free Software Foundation, Inc.
 See the end of the file for license conditions.
 
 
@@ -9,17 +8,30 @@ See the end of the file for license conditions.
 read the Windows-specific section near the end of this document.]
 
 ** When you debug Emacs with GDB, you should start it in the directory
-where the executable was made.  That directory has a .gdbinit file
-that defines various "user-defined" commands for debugging Emacs.
-(These commands are described below under "Examining Lisp object
-values" and "Debugging Emacs Redisplay problems".)
-
-** When you are trying to analyze failed assertions, it will be
-essential to compile Emacs either completely without optimizations or
-at least (when using GCC) with the -fno-crossjumping option.  Failure
-to do so may make the compiler recycle the same abort call for all
-assertions in a given function, rendering the stack backtrace useless
-for identifying the specific failed assertion.
+where the executable was made (the 'src' directory in the Emacs source
+tree).  That directory has a .gdbinit file that defines various
+"user-defined" commands for debugging Emacs.  (These commands are
+described below under "Examining Lisp object values" and "Debugging
+Emacs Redisplay problems".)
+
+Some GDB versions by default do not automatically load .gdbinit files
+in the directory where you invoke GDB.  With those versions of GDB,
+you will see a warning when GDB starts, like this:
+
+  warning: File ".../src/.gdbinit" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
+
+There are several ways to overcome that difficulty, they are all
+described in the node "Auto-loading safe path" in the GDB user manual.
+
+** When you are trying to analyze failed assertions or backtraces, it
+is essential to compile Emacs with flags suitable for debugging.
+With GCC 4.8 or later, you can invoke 'make' with CFLAGS="-Og -g3".
+With older GCC or non-GCC compilers, you can use CFLAGS="-O0 -g3".
+With GCC and higher optimization levels such as -O2, the
+-fno-omit-frame-pointer and -fno-crossjumping options are often
+essential.  The latter prevents GCC from using the same abort call for
+all assertions in a given function, rendering the stack backtrace
+useless for identifying the specific failed assertion.
 
 ** 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
@@ -406,6 +418,11 @@ stepping, you will see where the loop starts and ends.  Also, examine
 the data being used in the loop and try to determine why the loop does
 not exit when it should.
 
+You can also trying sending Emacs SIGUSR2, which, if `debug-on-event'
+has its default value, will cause Emacs to attempt to break it out of
+its current loop and into the Lisp debugger.  This feature is useful
+when a C-level debugger is not conveniently available.
+
 ** If certain operations in Emacs are slower than they used to be, here
 is some advice for how to find out why.
 
@@ -754,5 +771,3 @@ Local variables:
 mode: outline
 paragraph-separate: "[         \f]*$"
 end:
-
-;;; arch-tag: fbf32980-e35d-481f-8e4c-a2eca2586e6b