Emacs Mode for GDB


This mode turns Emacs into an IDE, using GDB as the underlying debugger, and was introduced in Emacs 22.1. It is described in more detail in the Emacs manual. However, most of it should be fairly intuitive. There is an old Linux Journal tutorial describing its basic use.

Recently released GDB 7.0 allows scripting with Python so that the implementation details of STL containers can be hidden when displaying them as watch expressions.

Here's a screenshot of Emacs 23.1.50 from the CVS repository at Savannah displaying the values of elements in various STL collections:


You can find further screenshots of Emacs as an IDE here.

GDB 7.0 also allows reverse execution where you can "rewind" the program by running it backwards. See the GDB manual for more detail. On the release branch of Emacs, at Savannah, this functionality can be accessed through the tool bar. To get this version, you need to do:

  cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/emacs co -r EMACS_23_1_RC emacs


  cvs up -r EMACS_23_1_RC

from the emacs directory if you have already checked Emacs out on trunk.

These features are available in Emacs 23.2.

If you set the alias below in your .cshrc, you can start debugging with the command "gdbtool <filename>" just like you would with a a graphical debugger like totalview or cvd. Be careful to ensure Emacs 23 is the first Emacs executable called emacs in your path, or adjust the alias accordingly.

  alias gdbtool emacs --eval \'\(gdb \"gdb --annotate=3 '\!*'\"\)\'

Or if you use a sh variant:

  gdbtool () { emacs --eval "(gdb \"gdb --annotate=3 $*\")";}

If you always have an instance of Emacs running then you could use emacsclient rather than emacs.

Eclipse CDT is another program that acts as an IDE and possibly has more features. If you have a large C++ project then this may better suit your needs. Emacs, on the other hand is not project based, provides a lightweight means of managing your files with a standard makefile and is perhaps more suited to smaller C projects and embedded programming. I think the biggest advantage of this mode over other debuggers is that the powerful features of Emacs are available for tasks such as editing and searching.

The FreeBSD Wiki describes Kernel Debugging with dcons with a screenshot of this mode using Emacs from a terminal.


The current mode uses an interface to GDB called annotations. This involves marking up GDB's output, which is really intended to be read by humans. This output changes with time and has variable formatting, so a more stable and precise machine interface called GDB/MI is being developed.

The GDB Graphical Interface as part of Emacs in trunk the CVS repository at Savannah now uses GDB/MI through a file called gdb-mi.el. This was improved by Dmitry Dzhus as part of the Google Summer of Code 2009 project Emacs GDB/MI migration to include the new feature of GDB, non-stop mode, where threads can be stopped, started and stepped on an individual basis. To get this from CVS, follow the instructions below. Read the debugger section of the Emacs manual of that version for further details.

This mode will eventually be much better than the current mode but, for now, for someone who just wants to use GDB in the regular manner, the current mode in Emacs 23.1 is probably a better option. It also needs GDB 7.0.

Caveat: GDB in Emacs has probably gone as far as I can take it with annotations. However, for whatever reason, over the years I have been unable to get many of my changes for GDB/MI into GDB. Unlike Emacs, there are commercial interests in GDB, and obviously patches that aren't aligned with those interests just represent a risk and make no business sense. So I anticipate that development of gdb-mi.el will falter unless those interests drive GDB in Emacs in the future.

Debugging Multi-process (MPI) Applications

Following this advice Emacs can be used to debug OpenMPI programs using:

  M-x gdb<RET>
  Run gdb (like this): /usr/bin/mpirun -np 13 mpigdb  path/to/executable<RET>

where mpigdb is the script:


  # $OMPI_MCA_ns_nds_vpid is the OpenMPI equivalent to $LAMRANK
  if [ "${OMPI_MCA_ns_nds_vpid}" == "0" ] ; then
    exec gdb --annotate=3 $*
    xterm -sb -rightbar -e "bash -c \"gdb $*<<EOF
  exit 0

Getting Emacs

A Guided Tour of Emacs gives a good illustrated introduction to Emacs 23 and includes a screenshot of this mode.

All of the major Linux distributions now include Emacs 22. Versions of these packages are also available as backports in Ubuntu (Edgy, Dapper and Breezy).

Mac OS X 10.5 (Leopard) also includes Emacs 22.1 as part of Darwin 9.0. This version has been built to support carbon, but you need to put an Emacs.app wrapper around it. For some reason M-x gdb has been changed to start up with "gdb --annotate=1". This is the same as "gdb --fullname" and so gives the old text command mode used in Emacs 21. To get the new graphical interface you need to change this back to "gdb --annotate=3". You can do this by editing the line in the minibuffer, or permanently with the custom variable "gud-gdb-command-name" using M-x customize-variable. Dan McKinley has a screenshot in his blog.

Alternatively you can download Emacs 23.1 as a tarball from here and build it yourself. Please report any problems using M-x report-emacs-bug which will include your configuration and send your message to the bug-gnu-emacs mailing list.

If you wish to use the most recent version, which uses GDB/MI, and you're not behind a firewall, you can get this directly from CVS, as described on Savannah:

  cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/emacs co emacs

Then read INSTALL.CVS in the emacs directory for further instructions. Once you've built Emacs you can keep updating to the new changes by doing:

  cvs up

from the emacs directory and following INSTALL.CVS. which really isn't much harder than downloading a tarball and will also mean that you can submit up-to-date suggestions or patches to the emacs-devel mailing list.

Multiple debug sessions

Note: These files have not been updated since January 2007.

The graphical interface described above can currently only be used to debug a single program at a time. Here are two files, multi-gud.el, multi-gdb-ui.el, that should allow multiple debug sessions within one invocation of Emacs. They still require Emacs 22 and need to be evaluated *instead* of gud.el and gdb-ui.el. For example you could put them in your load-path and have

  (load-library "multi-gud.el")
  (load-library "multi-gdb-ui.el")

in your .emacs. It is important that multi-gud.el is loaded first, otherwise multi-gdb-ui.el might find gud.el.

The're a bit rough but should basically do the right thing. They are not currently part of Emacs so it's probably best to report bugs/improvements directly to me.


There are many areas where this mode can be improved. Here are some ideas that I have had and some might be good candidate projects for GSoC 2010. If you have other ideas, I would like to hear them.