How do I debug an emacs crash?

Question

I am debugging why emacs crashes when using a function from a package¹. The aim of this debug process is to get useful data to submit using M-x report-emacs-bug.

To get help on how to debug emacs crashes, I have already looked at Emacs Manual - Crashing and Emacs Manual - After a Crash, but they did not help.

The After A Crash manual refers to emacs-buffer.gdb but I have no idea how to use it. While asking google for help, I came across this emacs.SE question, and I recompiled emacs using the -ggdb3 flags.

I have no prior experience using gdb and so I tried few failed attempts to use the emacs-buffer.gbd file.

Here's what I tried:

• gdb -x /path/to/emacs-buffer.gdb
• gdb -> file /path/to/emacs-buffer.gdb
• gdb -> source /path/to/emacs-buffer.gdb
• source /path/to/emacs-buffer.gdb

On a side note, emacs compiled with the -ggdb3 flag takes about 10 seconds longer to load; earlier it was 5-6 seconds, now about 16-17 seconds. I know the exact seconds because of a code that calculates that in my init. Is this increase in startup time expected?

---

_{Footnote 1: emacs crashes consistently when undo-tree tries to restore the undo history for a particular .org file (which I cannot share publicly). I have (setq undo-tree-auto-save-history t). This crash happens only on the emacs git master, not on emacs 24.5. On emacs 24.5, undo-tree throws an error stating that it's unable to load the undo history (even through the undo history file exists), but at least the emacs session does not crash on that version.}

Answer 1

The easiest way to debug an Emacs crash is to start Emacs under gdb, and then do whatever thing it is that reproduces the crash.

Assuming you're building your Emacs from source, you should pass CFLAGS="-O0 -g3" to the ./configure script. This makes the C compiler turn off optimisations (which can make things confusing while debugging) and activates maximum debug information in the executable. Run make to build Emacs.

Then, start gdb from within the src directory of your Emacs tree:

$ cd ~/my-emacs-tree/src
$ gdb ./emacs

On OSX, you'll want to pass --with-ns to the ./configure script and start gdb on the Emacs inside the created application:

$ cd ~/my-emacs-tree
$ make install
$ cd src
$ gdb nextstep/Emacs.app/Contents/MacOS/Emacs

The reason to start from the src directory is that there is a .gdbinit file that sets up useful GDB function definitions for debugging Emacs. If that file was loaded, you should see something like this when starting gdb:

DISPLAY = /private/tmp/com.apple.launchd.cNjhIdtUNd/org.macosforge.xquartz:0
TERM = xterm-256color
Breakpoint 1 at 0x1000ca444: file ../../src/emacs.c, line 353.
Breakpoint 2 at 0x1000e7e34: file ../../src/sysdep.c, line 926.

Type r to start Emacs. You can pass extra arguments on the same line, e.g. r --debug-init.

Then try to make Emacs crash. If it crashes, you should see a note about it in gdb, and you'll be left at the (gdb) prompt again. If Emacs doesn't crash, but freezes, you can hit C-z in the terminal where you're running gdb to get back to the prompt.

Once at the prompt, type bt to get a backtrace. As a bonus, if the Emacs .gdbinit file was correctly loaded, you'll see a Lisp backtrace after the C backtrace. Both backtraces are very useful things to include in M-x report-emacs-bug.

---

There is much more information, including how to examine the state of variables etc, in the etc/DEBUG file in the Emacs tree. You can open it by typing C-h C-d inside Emacs, or you can read it online.