An MPI debugger built on gdb
.
This is a temporary warning, until issue #23 is resolved. Due to an underlying issue with with gdbserver
it is not
recommended to run mdb
on multi-user systems connected to a public network e.g., most HPC systems.
Warning: gdbserver does not have any built-in security. Do not run gdbserver connected to any public network; a GDB connection to gdbserver provides access to the target system with the same privileges as the user running gdbserver.
(source gdb manual)
I am working on a fix which involves replacing the gdbserver
backend with my own tls
/ssl
-encrypted server to manage
connections and directly use gdb
as a backend instead.
I am planning to use randomly-generated tokens (similar to jupyter notebook
) to secure the connection.
For help with installation, a quick-start tutorial (with example debug session) and an API reference please check out mdb
's
documentation.
mdb
is a debugger aimed at parallel programs using the MPI programming paradigm. mdb
acts as a wrapper around gdb
and, as
such, it supports the following languages:
- C
- C++
- Fortran
Technically gdb
supports other languages as well, but this is the intersection of languages that MPI is implemented in.
Please see the quick start guide in the documentation for a walk-through of a simple debug session. The guide covers basic debug commands and information on how to launch the debugger.
These instructions are for normal use of mdb
. Please see below for a developer install.
-
Clone the repository.
git clone https://github.com/TomMelt/mdb.git
-
(optional - but recommended) Create a
conda
environment orvenv
.conda create -n mdb python conda activate mdb
-
Install
mdb
.cd mdb/ pip install .
More information can be found in the installation guide.
Please Note mdb
doesn't currently support Windows (see
here for more info).
gdb
gdbserver
mdb
does not package gdb
or gdbserver
. You will need these installed on your system in order to run mdb
. Please visit
GNU's website for information on how to install gdb
and gdbserver
on your system.
The main python dependencies are (see requirements.txt
):
click
matplotlib
numpy
pexpect
rich
These will all be installed as part of the default pip
installation. See installing
mdb in the documentation for more information.
termgraph
(optional - fancy Unicode plots straight to your terminal)
termgraph
is optional but can be installed alongside mbd
. See installing
mdb in the documentation for more information.
Currently I am building and testing for open MPI only. In principle it really won't take much work to expand to other implementations but I just haven't done it yet.
- Open MPI
mpirun
andmpiexec
- Intel MPI
mpirun
andmpiexec
- Slurm
srun
(should work but still needs testing) - others...
- rewrite launcher to add more functionality (e.g., auto-restart if MPI job fails)
- intercept
stdin
to run commands on another process (or processes) inside of an interactive session - track MPI communication dependencies (holistic metric)
- print aggregated backtrace (holistic metric)
- record asciinema demo? / youtube video?
If you would like to be involved in the development, feel free to submit a PR. A word of caution though... the code is currently in a highly volatile state and a plan major changes to the interface and layout. I will update this section when I reach a more stable part of the development. Either way changes are welcome at anytime.
Please see CONTRIBUTING.md for more details on how best to contribute.
For development it is best to install mdb
with some additional dependencies. These can be installed following the installing
mdb for developers guide.
This project was inspired by @mystery-e204's mpidb tool and @Azrael3000's tmpi tmux interface.
I have recently come across @robertu94's mpigdb. It seems to offer similar functionality
and it has a closer integration with gdb using gdb's inbuilt inferior
s to handle multiple processes at the same time (see
gdb manual sec. 4.9
for more info). The main difference from my perspective is that I can plot variables across MPI processes using mdb
and AFAIK
mpigdb
cannot. If you like mdb
you may want to check out mpigdb
as well.