Modular visual interface for GDB in Python.
This comes as a standalone single-file
.gdbinitwhich, among the other things, enables a configurable dashboard showing the most relevant information during the program execution. Its main goal is to reduce the number of GDB commands issued to inspect the current program status allowing the programmer to focus on the control flow instead.
.gdbinitin your home directory, for example:
wget -P ~ git.io/.gdbinit
- Single GDB init file.
- Write the dashboard to the main GDB console or to an external file/TTY.
- Interaction with GDB using the native Python API .
- Several default modules are included to address the most basic needs: source code, assembly, registers, etc.).
- User-defined modules can be easily developed by extending a Python class .
- Additional configuration files (both GDB and Python) are read from
- Fully stylable user interface and dynamic command prompt.
- No GDB command has been redefined, instead all the features are available as subcommands of the main
GDB dashboard requires at least GDB 7.7 compiled with Python 2.7 in order to work properly.
See #1 for more details/workarounds.
Additional GDB front ends
GDB dashboard is not meant to work seamlessly with additional front ends, e.g., TUI, Nemiver, etc. There are basically two options to work around this:
- Prevent the front from loading the
.gdbinitfile. For example, start TUI with
- Load GDB dashboard manually (only recommended if the front end is the most used option). Install as usual, then:
Finally from the GDB shell:
mv ~/.gdbinit ~/.gdb-dashboard
Follows the list of bundled default modules. Refer to the GDB help system for the full syntax.
assemblyshows the disassembled code surrounding the program counter. The instructions constituting the current statement are marked, if available.
historylists the last entries of the GDB value history.
memoryallows to inspect memory regions.
registersshows the CPU registers and their values.
sourceshows the program source code, if available.
stackshows the current stack trace including the function name and the file location, if available. Optionally list the frame arguments and locals too.
threadslists the currently available threads.
expressionswatches user expressions.
The GDB documentation is available at
help dashboard. Just like any GDB command, abbreviations are possible. Moreover, the alias
This is the root command and it is used to manually redisplay the dashboard.
dashboard -output [
By default the dashboard is written to the GDB console but it is possible to redirect its output to a file or even to another terminal. If the target is a valid terminal TTY then its width is used to format the dashboard, otherwise fall back to the width of the main GDB console.
Without argument reset this setting to the default.
Display the dashboard in another terminal
- start GDB in one terminal;
- open another terminal (e.g. tmux pane) and get its TTY with the
/dev/ttys001, the name may be different for a variety of reasons);
- issue the command
dashboard -output /dev/ttys001to redirect the dashboard output to the newly created terminal;
- debug as usual.
Display the dashboard in a web browser
Pushing this even further, one could use a web browser as an auxiliary terminal using gotty .
- start GDB in one terminal;
- open another terminal and execute
gotty sh -c 'tty; cat';
- open a web browser, navigate to
http://localhost:8080and note the TTY;
- issue the command
dashboard -output /dev/ttys001to redirect the dashboard output to the web browser;
- debug as usual.
dashboard -enabled [on|off]
Enable or disable the automatic display of the dashboard whenever the target program stops. The dashboard is enabled by default and even when it is disabled, it can be manually displayed with
Sometimes it may be convenient to redraw the dashboard even if the target program has not changed its execution status, for example when the programmer switches the currently selected frame with the
downcommands. It is possible to do so by setting up some GDB hooks in the user-defined init file , for example:
dashboard -layout [
By default, all the modules are enabled and placed within the dashboard in alphabetical order. As the number of modules grows, it is important to decide which modules will be part of the dashboard, and where.
Each directive is in the form
[!]<module>, when the
!is present then the corresponding module is disabled by default. The order of directives denotes the display order within the dashboard. For example:
Modules which do not appear in the list are disabled and placed after the last element in alphabetical order.
dashboard -layout source !assembly stack
When executed without arguments, this command lists all the available modules.
dashboard -style [
Access to the stylable attributes of the dashboard, see Stylable attributes . For example, to change the prompt to something more familiar:
The argument is parsed as a Python literal and converted to the proper type.
dashboard -style prompt '(gdb)'
When only the name is specified this command shows the current value, whereas without arguments prints all the attributes.
Every module adds its own subcommand
dashboard <module>which is used to toggle the enable flag and to redisplay the dashboard.
Modules may also declare additional subcommands, see
help dashboard <module>from GDB.
Moreover, if a module declare some stylable attributes then the command
dashboard <module> -stylewill be available. Its functioning is equivalent to the
dashboard -stylecommand but it does apply to a module.
~/.gdbinit.d/are executed in alphabetical order, but the preference is given to Python files. If there are subdirectories, they are walked recursively. The idea is to keep separated the custom modules definition from the configuration itself.
The main configuration file can be placed in
~/.gdbinit.d/init) and should be used to tune the dashboard styles and modules configuration but also the usual GDB parameters.
The alternative is to hard code changes in the provided
.gdbinit, to do so just add new modules and GDB settings under
# Default modulesand
# Better GDB defaultsrespectively.
There is number of attributes that can be used to customize the aspect of the dashboard and of its modules. They are documented within the GDB help system. For what concerns the dashboard itself it can be reached with:
Whereas for modules:
help dashboard -style
help dashboard <module> -style
ANSI escape codes
Colors and text styles are specified using ANSI escape codes. For example setting a style to
^[[1;31m, which will result in displaying the text red (
31) and bright (
1). The ANSI output can be disabled by setting the
ansiattribute (note that this will not affect the command prompt).
A divider is basically a terminal-wide horizontal line with an optional label. Primary dividers are those used to separate the modules, whereas secondary dividers may be used inside modules to logically separate different sections. When a section or module is empty then the styles used for the divider are those with the
These are general purpose ANSI styles defined for convenience and used within the default modules.
The idea of custom modules is that they provide ways to access readonly information from the target program status; it is safe to assume that they will be queried during the program execution only.
Custom modules must inherit the
Dashboard.Moduleclass and define some methods:
labelreturns the module label which will appear in the divider.
linesreturn a list of strings which will form the module content. When a module is temporarily unable to produce its content, it should return an empty list; its divider will then use the styles with the
Modules are instantiated once at initialization time and kept during the whole the GDB session.
Optionally, a module may include a description which will appear in the GDB help system by specifying a Python docstring for the class.
Optionally, a module may define stylable attributes by defining the
attributesmethod returning a dictionary in which the key is the attribute name and the value is another dictionary:
defaultis the initial value for this attribute.
docis the documentation of this attribute which will appear in the GDB help system. This key can be omitted.
nameis the name of the attribute of the Python object, defaults to the key value.
typeis the type of this attribute, it is used to coerce the value passed as an argument to the proper type, or raise an exception. This key defaults to the
checkis a control callback which accept the coerced value and returns
Trueif the value satisfies the constraint and
Falseotherwise. This key is optional, when omitted no check is performed.
commandsmethod returning a dictionary in which the key is the command name and the value is another dictionary:
actionis the callback to be executed which accepts the raw input string from the GDB prompt. Callbacks may raise exceptions to notify erroneous situations which message will be shown automatically to the user.
docis the command documentation.
completionis the completion policy, one of the
gdb.COMPLETE_*constants defined in the reference manual . This key is optional and defaults to
Nonewhich is equivalent to
A number of auxiliary common functions are defined in the global scope, they can be found in the provided
.gdbinitand concern topics like ANSI output, divider formatting, conversion callbacks, etc. They should be more or less self-documented, some usage examples can be found within the bundled default modules.
Default modules already provide a good example, but here is a simple module which may be used as a template for new custom modules, it allows the programmer to note down some snippets of text during the debugging session.
To use the above just save it in a Python file, say
"""Simple user-defined notes."""
self.notes = 
out = 
for note in self.notes:
return out[:-1] if self.divider else out
def add(self, arg):
raise Exception('Cannot add an empty note')
def clear(self, arg):
self.notes = 
'doc': 'Add a note.'
'doc': 'Remove all the notes.'
'doc': 'Divider visibility flag.',
~/.gdbinit.d/, the following commands (together with the help) will be available:
dashboard notes add
dashboard notes clear
dashboard notes -style