Debugging GNU Emacs
-Copyright (C) 1985, 2000-2015 Free Software Foundation, Inc.
+Copyright (C) 1985, 2000-2016 Free Software Foundation, Inc.
See the end of the file for license conditions.
** Preliminaries
*** Use the Emacs GDB UI front-end
We recommend using the GUI front-end for GDB provided by Emacs. With
-it, you can start GDB by typing "M-x GDB RET". This will suggest the
-default binary to debug; if you are going to start a new Emacs
-process, change it as needed to point to the correct binary.
-Alternatively, if you want to attach the debugger to an already
-running Emacs process, change the GDB command shown in the minibuffer
-to say this:
+it, you can start GDB by typing "M-x gdb RET". This will suggest the
+file name of the default binary to debug; if the suggested default is
+not the Emacs binary you want to debug, change the file name as
+needed. Alternatively, if you want to attach the debugger to an
+already running Emacs process, change the GDB command shown in the
+minibuffer to say this:
gdb -i=mi -p PID
These are displayed as integer values (or structures, if you used the
"--enable-check-lisp-object-type" option at configure time) that are
hard to interpret, especially if they represent long lists. You can
-use the 'pp' command to display them in their Lisp form. Additional
-information about displaying Lisp objects can be found under
-"Examining Lisp object values" below.
+use the 'pp' command to display them in their Lisp form. That command
+displays its output on the standard error stream, which you
+can redirect to a file using "M-x redirect-debugging-output".
+This means that if you attach GDB to a running Emacs that was invoked
+from a desktop icon, chances are you will not see the output at all,
+or it will wind up in an obscure place (check the documentation of
+your desktop environment).
+
+Additional information about displaying Lisp objects can be found
+under "Examining Lisp object values" below.
The rest of this document describes specific useful techniques for
debugging Emacs; we suggest reading it in its entirety the first time
To see the current value of a Lisp Variable, use 'pv variable'.
+These commands send their output to stderr; if that is closed or
+redirected to some file you don't know, you won't see their output.
+This is particularly so for Emacs invoked on MS-Windows from the
+desktop shortcut. You can use the command 'redirect-debugging-output'
+to redirect stderr to a file.
+
Note: It is not a good idea to try 'pr', 'pp', or 'pv' if you know that Emacs
is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
due to stack overflow), or crucial data structures, such as 'obarray',
[...]
}
-Now we can use 'pr' to print the frame parameters:
+Now we can use 'pp' to print the frame parameters:
(gdb) pp $->param_alist
((background-mode . light) (display-type . color) [...])
On GNU and Unix systems, 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.
+debugger. (See the node "Debugging" in the ELisp manual for the
+details about 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.