The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX, SDB or XDB if you have them. GUD can also serve as an interface to the Perl's debugging mode, the Python debugger PDB, and to JDB, the Java Debugger.
There are several commands for starting a debugger, each corresponding to a particular debugger program.
Run GDB as a subprocess of Emacs. This command creates a buffer for input and output to GDB, and switches to it. If a GDB buffer already exists, it just switches to that buffer.
Similar, but run DBX instead of GDB.
Similar, but run XDB instead of GDB. Use the variable gud-xdb-directories to specify directories to search for source files.
Similar, but run SDB instead of GDB.
Some versions of SDB do not mention source file names in their messages. When you use them, you need to have a valid tags table (Section 24.16) in order for GUD to find functions in the source code. If you have not visited a tags table or the tags table doesn't list one of the functions, you get a message saying The sdb support requires a valid tags table to work. If this happens, generate a valid tags table in the working directory and try again.
Run the Perl interpreter in debug mode to debug file, a Perl program.
Run the Java debugger to debug file.
Run the Python debugger to debug file.
Each of these commands takes one argument: a command line to invoke the debugger. In the simplest case, specify just the name of the executable file you want to debug. You may also use options that the debugger supports. However, shell wildcards and variables are not allowed. GUD assumes that the first argument not starting with a - is the executable file name.
Emacs can only run one debugger process at a time.
When you run a debugger with GUD, the debugger uses an Emacs buffer for its ordinary input and output. This is called the GUD buffer. The debugger displays the source files of the program by visiting them in Emacs buffers. An arrow (=>) in one of these buffers indicates the current execution line.[1] Moving point in this buffer does not move the arrow.
You can start editing these source files at any time in the buffers that were made to display them. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables.
If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them. Section 31.15.3.
The GUD interaction buffer uses a variant of Shell mode, so the commands of Shell mode are available (Section 31.15.3). GUD mode also provides commands for setting and clearing breakpoints, for selecting stack frames, and for stepping through the program. These commands are available both in the GUD buffer and globally, but with different key bindings.
The breakpoint commands are usually used in source file buffers, because that is the way to specify where to set or clear the breakpoint. Here's the global command to set a breakpoint:
Set a breakpoint on the source line that point is on.
Here are the other special commands provided by GUD. The keys starting with C-c are available only in the GUD interaction buffer. The key bindings that start with C-x C-a are available in the GUD interaction buffer and also in source files.
Display in another window the last line referred to in the GUD buffer (that is, the line indicated in the last location message). This runs the command gud-refresh.
Execute a single line of code (gud-step). If the line contains a function call, execution stops after entering the called function.
Execute a single line of code, stepping across entire function calls at full speed (gud-next).
Execute a single machine instruction (gud-stepi).
Continue execution without specifying any stopping point. The program will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (gud-cont).
Delete the breakpoint(s) on the current source line, if any (gud-remove). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.
Set a temporary breakpoint on the current source line, if any. If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.
The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available:
Select the next enclosing stack frame (gud-up). This is equivalent to the up command.
Select the next inner stack frame (gud-down). This is equivalent to the down command.
If you are using GDB, these additional key bindings are available:
With GDB, complete a symbol name (gud-gdb-complete-command). This key is available only in the GUD interaction buffer, and requires GDB versions 4.13 and later.
Run the program until the selected stack frame returns (or until it stops for some other reason).
These commands interpret a numeric argument as a repeat count, when that makes sense.
Because TAB serves as a completion command, you can't use it to enter a tab as input to the program you are debugging with GDB. Instead, type C-q TAB to enter a tab.
On startup, GUD runs one of the following hooks: gdb-mode-hook, if you are using GDB; dbx-mode-hook, if you are using DBX; sdb-mode-hook, if you are using SDB; xdb-mode-hook, if you are using XDB; perldb-mode-hook, for Perl debugging mode; jdb-mode-hook, for PDB; jdb-mode-hook, for JDB. You can use these hooks to define custom key bindings for the debugger interaction buffer. Section 32.2.3.
Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer:
(gud-def function cmdstring binding docstring) |
This defines a command named function which sends cmdstring to the debugger process, and gives it the documentation string docstring. You can use the command thus defined in any buffer. If binding is non-nil, gud-def also binds the command to C-c binding in the GUD buffer's mode and to C-x C-a binding generally.
The command string cmdstring may contain certain %-sequences that stand for data to be filled in at the time function is called:
The name of the current source file. If the current buffer is the GUD buffer, then the "current source file" is the file that the program stopped in.
The number of the current source line. If the current buffer is the GUD buffer, then the "current source line" is the line that the program stopped in.
The text of the C lvalue or function-call expression at or adjacent to point.
The text of the hexadecimal address at or adjacent to point.
The numeric argument of the called function, as a decimal number. If the command is used without a numeric argument, %p stands for the empty string.
If you don't use %p in the command string, the command you define ignores any numeric argument.
The Tooltip facility (Section 19.18) provides support for GUD. If GUD support is activated by customizing the tooltip group, variable values can be displayed in tooltips by pointing at them with the mouse in the GUD buffer or in source buffers with major modes in the customizable list tooltip-gud-modes.
| [1] | Under a window system the arrow is displayed in the marginal area of the Emacs window. |