Debugging Emacs

[Phillip Lord]

I debugged Emacs core the other day for the first time. As I have no
experience with C, GDB or any of the Emacs tooling, I found this an
uphill struggle, so I have written up a short "how-to-debug" Emacs file.

It starts from a slightly earlier place than the current DEBUG file, and
is a step by step guide. The existing DEBUG file, I found pretty dense.

I was wondering if it is worth including first? Also, if my approach to
debugging is a good one, in case I am doing something daft. Comments
welcome.



** How to Debug Emacs C core

The following is a brief introduction on how to debug the C core of Emacs. It
assumes reasonable programming knowledge, but not particular knowledge of the
tooling, other than an understanding of how to build Emacs.

This is not a normative guide -- there are many ways to use these tools to
debug Emacs. It's a "hello world" guide. It describes one way that should work.

*** Preparing Emacs to be debugged

To debug Emacs, you need to build it from the tarball source file. First,
Emacs should be compiled with the correct flags to ensure that it can be
debugged cleanly.

This is achieve with the configure script which should be launched with the
following command line.

./configure --enable-checking --enable-check-lisp-object-type --config-cache 
CFLAGS="-Og -g3"

Strictly, only the CFLAGS part is necessary for debugging. The two "--enable"
flags will pick up some errors for you, and the --config-cache makes configure
run more quickly second time around (useful if you are switching between
branches in git).

Then to build type.

make

You do not need to install Emacs. It runs fine from a source build.

*** Preparing GDB

We will debug with GDB. Emacs comes with a nice set of configuration files for
working with GDB, with many useful functions. To use this, it needs to be
loaded first. Unfortunately, by default GDB disallows this, as it's a security
risk. So, you need to add the following line to your .gdbinit file.

add-auto-load-safe-path path/emacs/src/.gdbinit

This line will is actually printed out by GDB at start up (along with a lot of
other text), so you can copy it from there.
 
*** Preparing your debugging Emacs

We will debug Emacs using Emacs of course. You can debug and use the same
installation of Emacs if you choose. Or you can use an older, stable release.

Debugging with GDB uses quite a bit of screen space. If you do not have a
relatively large screen, then it decrease the font size to about the smallest
you can cope with.

Now open one of the source files of Emacs, found in the emacs/src directory.


*** Starting GDB

Start GDB directly from Emacs. If you do this from a buffer with a Emacs
source file, the it will start in the correct directory, which has to be the
src of Emacs, so that GDB will read the .gdbinit file described earlier.

M-x gdb

Change "bootstrap-emacs" to "emacs".


Next we will open lots of windows, most of which you will need. Unfortunately,
if you are reading this file in the same Emacs, you may no longer be able to
the file, but you can switch back to it as normal.

Now type,

M-x gdb-many-windows

If you want to restore this window configuration later, then

M-x gdb-restore-windows

will work.

One unfortunate side effect of the .gdbinit script is that it's hard to stop
Emacs when it has started, so we add a breakpoint somewhere in C in a function
that is not likely to be called. This will enable us to get Emacs to stop.

So, open the file floatfns.c and find the "log" function (search for "Flog").
You can set a breakpoint using the GDB menu, or by clicking in the fringe. If
you want to save this breakpoint for later use, try:

save breakpoint bplog.txt

in the GDB window. You can source it later.




*** Starting and Debugging Emacs


Now start Emacs. In the GBD window, type:

run -Q

(the -Q gets passed straight to Emacs. Add other options if you want).


GDB will now produce lots of output. Next type "continue" in the GDB window.
Emacs will now start. In this Emacs (not the one you launched GDB with) try
M-: (log 10)

This Emacs should now hang, and floatfns.c should have popped up.

The first argument to the log function is called, prosaically, "arg".
We can print the value of this, using the print command.


(gdb) print arg
$1 = {
  i = 42
}

Unfortunately, because it's actually a LispObject, that is now terrible
useful. If you want to see the "real" value, then try

pp arg

instead. This prints to the window "*input/output of emacs*" where you should
see

10

Another useful function is ppt which brings point

(gdb) ppt
BUF PT: 192[196] of 1..192[196] GAP: 192[196] SZ=2000

There are many more, and emacs/src/.gbdinit is worth reading in full.