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.
-[People who debug Emacs on Windows using Microsoft debuggers
-should read the Windows-specific section near the end of this
-document.]
+[People who debug Emacs on Windows using Microsoft debuggers should
+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
handle SIGINT stop nopass
After this `handle' command, SIGINT will return control to GDB. If
-you want the C-g to cause a QUIT within Emacs as well, omit the
-`nopass'.
+you want the C-g to cause a QUIT within Emacs as well, omit the `nopass'.
A technique that can work when `handle SIGINT' does not is to store
the code for some character into the variable stop_character. Thus,
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.
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.
+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.
Building Emacs like that activates many assertions which scrutinize
display code operation more than Emacs does normally. (To see the
code which tests these assertions, look for calls to the `xassert'
-macros.) Any assertion that is reported to fail should be
-investigated.
+macros.) Any assertion that is reported to fail should be investigated.
Building with GLYPH_DEBUG defined also defines several helper
functions which can help debugging display code. One such function is
`dump_glyph_matrix'. If you run Emacs under GDB, you can print the
contents of any glyph matrix by just calling that function with the
matrix as its argument. For example, the following command will print
-the contents of the current matrix of the window whose pointer is in
-`w':
+the contents of the current matrix of the window whose pointer is in `w':
(gdb) p dump_glyph_matrix (w->current_matrix, 2)
because Emacs replaces the system's memory allocation functions with
its own versions, and because the dumping process might be
incompatible with the way these packages use to track allocated
-memory. Here are some of the changes you might find necessary
-(SYSTEM-NAME and MACHINE-NAME are the names of your OS- and
-CPU-specific headers in the subdirectories of `src'):
-
- - In src/s/SYSTEM-NAME.h add "#define SYSTEM_MALLOC".
+memory. Here are some of the changes you might find necessary:
- - In src/m/MACHINE-NAME.h add "#define CANNOT_DUMP" and
- "#define CANNOT_UNEXEC".
+ - Edit configure, to set system_malloc and CANNOT_DUMP to "yes".
- Configure with a different --prefix= option. If you use GCC,
version 2.7.2 is preferred, as some malloc debugging packages
mode: outline
paragraph-separate: "[ \f]*$"
end:
-
-;;; arch-tag: fbf32980-e35d-481f-8e4c-a2eca2586e6b
HCoop / bpt / emacs.git / blobdiff