The Grand "Cathedral" Debugger rewrite
Emacs Lisp Shell Makefile M4 Python Ruby Other
Failed to load latest commit information.
etc Add a bit of padding around the logo to make GitHub happy Jun 1, 2016
realgud One more FSF copyright assignment Jul 12, 2016
test Warn if gdb --interpreter=mi or -i mi is used Jun 28, 2016
.gitignore Revert "Revert "Manually generate "recursive" autoloads for subdirect… Jun 4, 2016
.travis.yml Try to fix travis #3 Mar 28, 2015
AUTHORS rdebug.el: make more user-friendly for interactive dbgr-track-from-re… Dec 9, 2009
COPYING Add GPL COPYING file Feb 13, 2015
Cask Fill in missing bits of Cask file May 30, 2016
ChangeLog Create ring of frame positions. Next/prev motion uses this. Also we have Nov 28, 2010
INSTALL A few more link updates (+ small edits in Commentary) Jun 4, 2016
Makefile.am Move test helper into test Feb 17, 2015
NEWS Start the Grand Unified Debugger Rewrite. Oct 28, 2009
README.md Merge branch 'master' into 103-jump Jun 6, 2016
THANKS Alway late on this kind of thing. May 30, 2016
autogen.sh realgud.el, autogen.el: More things to make dbgr->realgud renmaming w… Apr 1, 2013
common.mk Administration build stuff Jun 8, 2013
compute-lispdir.sh Fix up spelling when giving an error and regularize options given to … Nov 18, 2013
configure.ac Merge branch 'ipdb' of https://github.com/seanfarley/emacs-dbgr into … Feb 28, 2016
copyright_exceptions Fix logic for finding region to work on in tracking Mar 28, 2015
el-get-install.el Remove dependency on list-utils Feb 13, 2015
elisp-comp elisp-comp: recompile only if necessary. realgud.el: add dependent pa… Feb 9, 2014
install-from-git.sh realgud.el: Don't try to load gub for now. It's broken and melpa does… Nov 17, 2013
realgud-recursive-autoloads.el Revert "Revert "Manually generate "recursive" autoloads for subdirect… Jun 4, 2016
realgud.el Suppress irrelevant compilation warnings Jun 28, 2016

README.md

Build Status MELPA MELPA Stable

RealGUD logo

A modular GNU Emacs front-end for interacting with external debuggers, brought to you by Rocky Bernstein (@rocky) and Clément Pit-Claudel (@cpitclaudel).

RealGUD screenshot

Setup

You can install RealGUD from MELPA, a repository of Emacs packages. If you don't have MELPA set up, add the following to your .emacs and restart Emacs:

(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t)
(package-initialize)

You can then run the following commands to install RealGUD:

M-x package-refresh-contents RET      (to refresh your package database)
M-x package-install RET realgud RET   (to install and compile `realgud` and its dependencies)

Alternatively, you can install RealGUD using el-get or from source directly. See this article in our wiki for more info.

Quick start

Use M-x load-library RET realgud RET to load RealGUD.

Launching the debugger

Open a source file, then use M-x realgud:<debugger-name> to start your favorite debugger (for example, you can use M-x realgud:pdb to launch PDB, a Python debugger). RealGUD opens two windows: the command window (showing the debugger's REPL), and the source window, showing your code (with some debuggers, such as realgud:gdb, this window does not appear until you type start in the command window). An solid arrow indicates the current line in the source window. Grayed out arrows indicate previous positions.

Using the debugger

All usual debugger commands work in the command window: for example, you can type n RET in the command window to step forward one source line. But RealGUD's power lies in the source window: in it, most single keys correspond to a debugger action. For example, you can press n in the source window to step forward.

Source window commands

Here is a quick rundown of the most useful commands. “🐁” indicates mouse commands (commands that can be run by clicking on a variable or in the margins). Many of the commands are accessible from the tool bar (tool-bar-mode) and the menu (menu-bar-mode).

  • Motion commands

    Command Action
    n, F10 Next (aka “step over”, “step through”)
    s, SPC, F11 Step (aka “step into”)
    f, S-F11 Finish (aka “step out”, “return”)
    c, F5 Continue (run to next break point)
  • Using breakpoints

    Command Action
    b, F9 Set breakpoint 🐁
    D Clear breakpoint 🐁 (by number)
  • Inspecting variables

    Command Action
    mouse-2 (middle button) Inspect variable under cursor (in tooltip) 🐁
    e Evaluate expression
  • Control commands

    Command Action
    q, S-F5 Quit
    R, r Run (aka “restart”)
    S Go to command window

Supported debuggers

RealGUD supports many external debuggers. Help us support even more!

Advanced topics

Extra commands

“⚙” indicates a work-in-progress (contributions welcome!)

Command Action
U Until (run to a greater source line)
u, > Up stack (move to older stack frame)
d, < Down stack (move to younger stack frame)
X Clear breakpoint (by line)
j Jump to current line ⚙
- Disable breakpoint ⚙
+ Enable breakpoint ⚙

Tracking an existing debugger process

Use M-x realgud-track-mode inside an existing shell, or eshell buffer to track an already-running debugger process.

RealGUD's wiki

Browse the wiki for more information about setting up, using realgud, exploring features, and lots more.