Modular visual interface for GDB in Python.
This comes as a standalone single-file .gdbinit
which enables a configurable dashboard showing the most relevant information of the program being debugged. 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.
Just place .gdbinit
in your home directory, for example with:
wget -P ~ git.io/.gdbinit
Optionally install Pygments to enable syntax highlighting:
pip install pygments
Then debug as usual, the dashboard will appear automatically when the inferior program is paused. Commands and configurations can be reached via the dashboard
GDB command while help dashboard
is a good starting point to learn about all the functions.
-
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
~/.gdbinit.d/
. -
Fully stylable user interface and dynamic command prompt.
-
Optional syntax highlighting using the Pygments Python library.
-
No GDB command has been redefined, instead all the features are available as subcommands of the main
dashboard
command.
GDB dashboard requires at least GDB 7.7 compiled with Python 2.7 in order to work properly, see #1 for more details and possible workarounds. To find the Python version used by GDB run:
gdb --batch -ex 'python import sys; print(sys.version)'
Make sure that the system locale is configured to use UTF-8, in most cases it already is, otherwise (in case of UnicodeEncodeError
errors) a simple solution is to export the following environment variable:
export LC_CTYPE=C.UTF-8
On Windows the windows-curses
Python package is needed in order to obtain the correct terminal size.
Follows the list of bundled default modules, refer to the GDB help system for the full syntax.
assembly
shows the disassembled code surrounding the program counter. The instructions constituting the current statement are marked, if available.
history
lists the last entries of the GDB value history.
memory
allows to inspect memory regions.
registers
shows the CPU registers and their values.
source
show the program source code, if available.
stack
shows the current stack trace including the function name and the file location, if available. Optionally lists the frame arguments and locals too.
threads
lists the currently available threads.
variables
shows arguments and locals of the selected frame.
expressions
watches user expressions.
By default the dashboard is displayed in the GDB terminal but the -output
command of both the dashboard and modules can change this behavior. When the output of a module is not specified then the global output is used.
It may be useful to move the dashboard to another terminal so the main terminal can be used exclusively for GDB commands and target I/O.
To do so:
-
start GDB in one terminal;
-
open another terminal (e.g. tmux pane) and get its TTY with the
tty
command (e.g./dev/ttys001
, the name may be different for a variety of reasons); -
issue the command
dashboard -output /dev/ttys001
to redirect the dashboard output to the newly created terminal; -
debug as usual.
It is also possible to display the output of one or more modules to individual terminals. If two or more modules share the same output, they will be stacked as usual.
To do so:
-
start GDB in one terminal;
-
open another terminal and get its TTY with the
tty
command; -
pick a module, say
source
, then issue the commanddashboard source -output /dev/ttys001
to redirect its output to the newly created terminal; -
repeat for any other modules;
-
debug as usual.
Pushing this even further, one could use a web browser as an auxiliary terminal using gotty. Of course, using the method described above, one can also display the output of individual modules in one or more web browser instances.
To do so:
-
start GDB in one terminal;
-
open another terminal and execute
gotty sh -c 'tty; cat'
; -
open a web browser, navigate to
http://localhost:8080
and note the TTY; -
issue the command
dashboard -output /dev/ttys001
to redirect the dashboard output to the web browser; -
debug as usual.
The GDB documentation is available at help dashboard
. Just like any GDB command, abbreviations are possible, so da
, dash
, etc. all resolve to dashboard
.
This is the root command and it is used to manually redisplay the dashboard.
Display and optionally write to <file>
the current configuration (layout, styles, outputs). This command allows to configure the dashboard live then make the changes permanent, for example:
dashboard -configuration ~/.gdbinit.d/auto
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.
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 dashboard
.
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 up
or down
commands. It is possible to do so by setting up some GDB hooks in the user-defined init file, for example:
define hookpost-up
dashboard
end
define hookpost-down
dashboard
end
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:
dashboard -layout source !assembly stack
Modules which do not appear in the list are disabled and placed after the last element in alphabetical order.
When executed without arguments, this command lists all the available modules in the form of a list of directives followed by the status of the output files of the modules.
Access to the stylable attributes of the dashboard, see Stylable attributes. For example, to change the prompt to something more familiar:
dashboard -style prompt '(gdb)'
The argument is parsed as a Python literal and converted to the proper type.
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.
There are two additional predefined subcommands: -style
and -output
.
If a module declares some stylable attributes then the command dashboard <module> -style
will be available. Its functioning is equivalent to the dashboard -style
command but it does apply to a module.
Similarly, the dashboard <module> -output
mimics the dashboard -style
command but allows a finer grain of operation.
Files in ~/.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.
By convention, the main configuration file should be placed in ~/.gdbinit.d/
(say ~/.gdbinit.d/init
) and can 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 modules
and # Better GDB defaults
respectively.
GDB natively support the auto-loading of .gdbinit
files, this can come in handy to set up a different dashboard style according to the current project type (e.g., C++ development, reverse engineering, etc.). This feature is disabled by default for security reasons. To enable the auto-loading everywhere in the file system add this line to the main configuration file:
set auto-load safe-path /
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:
help dashboard -style
Whereas for modules:
help dashboard <module> -style
Colors and text styles are specified using ANSI escape codes. For example setting a style to 1;31
will produce ^[[1;31m
, which will result in displaying the text red (31
) and bright (1
). The ANSI output can be disabled by setting the ansi
attribute to False
(note that this will not affect the command prompt).
When the ansi
attribute is set to True
the Pygments Python library may be used by modules to provide syntax highlighting of the source code.
The syntax_highlighting
stylable attribute is a string which defines the Pygments style to use.
The list of all the available styles can be obtained with (from GDB itself):
python
from pygments.styles import *
for style in get_all_styles():
print(style)
end
To conveniently cycle through and try each available style:
python
from pygments.styles import *
for style in get_all_styles():
command = 'dashboard -style syntax_highlighting {!r}'.format(style)
gdb.execute(command)
print(command)
if input('Done? (y/N) ') == 'y':
break
end
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 off
qualifier.
These are general purpose ANSI styles defined for convenience and used within the default modules:
style_selected_1
;style_selected_2
;style_low
;style_high
;style_error
;style_critical
.
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.Module
class and define some methods:
-
label
returns the module label which will appear in the divider; -
lines
return 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 theoff
qualifier.
The name of a module is automatically obtained by the class name.
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 attributes
method returning a dictionary in which the key is the attribute name and the value is another dictionary:
-
default
is the initial value for this attribute; -
doc
is the optional documentation of this attribute which will appear in the GDB help system; -
name
is the name of the attribute of the Python object, defaults to the key value; -
type
is the type of this attribute defaulting to thestr
type, it is used to coerce the value passed as an argument to the proper type, or raise an exception; -
check
is an optional control callback which accept the coerced value and returnsTrue
if the value satisfies the constraint andFalse
otherwise.
Optionally, a module may declare subcommands by defining the commands
method returning a dictionary in which the key is the command name and the value is another dictionary:
-
action
is the callback to be executed which accepts the raw input string from the GDB prompt, exceptions will be shown automatically to the user; -
doc
is the command documentation; -
completion
is the optional completion policy, one of thegdb.COMPLETE_*
constants defined in the reference manual.
A number of auxiliary common functions are defined in the global scope, they can be found in the provided .gdbinit
and 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.
class Notes(Dashboard.Module):
"""Simple user-defined notes."""
def __init__(self):
self.notes = []
def label(self):
return 'Notes'
def lines(self, term_width, term_height, style_changed):
out = []
for note in self.notes:
out.append(note)
if self.divider:
out.append(divider())
return out[:-1] if self.divider else out
def add(self, arg):
if arg:
self.notes.append(arg)
else:
raise Exception('Cannot add an empty note')
def clear(self, arg):
self.notes = []
def commands(self):
return {
'add': {
'action': self.add,
'doc': 'Add a note.'
},
'clear': {
'action': self.clear,
'doc': 'Remove all the notes.'
}
}
def attributes(self):
return {
'divider': {
'doc': 'Divider visibility flag.',
'default': True,
'type': bool
}
}
To use the above just save it in a Python file, say notes.py
, inside ~/.gdbinit.d/
, the following commands (together with the help) will be available:
dashboard notes
dashboard notes add
dashboard notes clear
dashboard notes -style
GDB dashboard is not meant to work seamlessly with additional front ends, e.g., TUI, Nemiver, QtCreator, etc.
There are basically two options to work around this:
-
if the main debugging tool is GDB dashboard then it is recommended to prevent the front end from loading the
.gdbinit
file, they usually have an option to do so; -
otherwise it is possible to load GDB dashboard manually, that is, install as usual then:
mv ~/.gdbinit ~/.gdb-dashboard
Finally load it when needed from the GDB shell:
source ~/.gdb-dashboard
- GDB Python API