Recommended Debugging Approaches in MsPASS

Debugging in C++

There could be a possibility that you might get an error in the C++ code when using MsPASS, and here is a way you could try to debug and figure it out.

A suggested way to debug in C++ is using gdb.

First of all, you need to have gdb installed on your local computer. For those macOS users, you might encounter a problem when using gdb, at least for me. The error message will look like this Unable to find Mach task port for process-id 83767: (os/kern) failure (0x5). The problem is that you are not logged in as a root user (which you don't want). You need to create a certificate for gdb to be allowed access and codesign the gdb executable. If you have this issue, you have to follow this guide to make it work. Alternatively, you could use lldb on macOS to debug the C++ program and the process is exactly the same as gdb.

Next, you have to set the default_build_type to be Debug to allow cmake to compile code with debugging information. You should change that at the beginning of the mspass/cxx/CMakeLists.txt file. Then, you would run cmake and make to build the C++ library. You could follow the instructions under the section Running cmake in the Compiling MsPASS from source code page in our Wiki.

After compiling and linking the source code, you would obtain some target binaries and they are executables. Then you could run gdb or lldb to debug the code. We recommend you could follow the test files in the cxx/test folder. We use ctest to test the functionality of our C++ code, but you could write your custom test file and debug the functionality on your own.

gdb offers a big list of commands, however, the following commands cited are the ones used most frequently:

b main - Puts a breakpoint at the beginning of the program

b - Puts a breakpoint at the current line

b N - Puts a breakpoint at line N

b +N - Puts a breakpoint N lines down from the current line

b fn - Puts a breakpoint at the beginning of function "fn"

d N - Deletes breakpoint number N

info break - list breakpoints

r - Runs the program until a breakpoint or error

c - Continues running the program until the next breakpoint or error

f - Runs until the current function is finished

s - Runs the next line of the program

s N - Runs the next N lines of the program

n - Like s, but it does not step into functions

u N - Runs until you get N lines in front of the current line

p var - Prints the current value of the variable "var"

bt - Prints a stack trace

u - Goes up a level in the stack

d - Goes down a level in the stack

q - Quits gdb

For more information, you could always refer to the official gdb documentation.

Debugging in Python

First of all, for errors because of incorrect usage, you might need to turn to our wiki page for reference, which contains the user manual focusing on how we design each concept and feature, and reference manual documenting Python and C++ APIs.

For other bugs and issues that you are unable to resolve, please report them as issues in our GitHub.

If you would like to debug it by yourself, we suggest that you could follow the way how we write our test cases under python/tests folders. Basically, you could write a function as a unit testcase and test the functionality you would like to in your workflow. Some syntactic sugars in pytest would help if you would like to test some more complex workflows.

Then make sure you install pytest beforehand and assuming your shell is at the top of the mspass tree (i.e. in the mspass directory) type the following into your terminal window:

pytest --cov=mspasspy python/tests/path_to_your_test_case.py

Make sure you type the correct path of the unit test file you would like to run and you would see the result and debug it by yourself.

However, a more convenient and easier approach is make use of pdb, which is like a python version of gdb.

The module pdb defines an interactive source code debugger for Python programs. It supports setting (conditional) breakpoints and single stepping at the source line level, inspection of stack frames, source code listing, and evaluation of arbitrary Python code in the context of any stack frame. It also supports post-mortem debugging and can be called under program control. By default, it's installed as a package when you install python.

There are two ways you could use pdb.

1. non-invasive:

python3 -m pdb filename.py

In this way, you don't need to modify the source code and debug the program under terminal

2. invasive:

import pdb;pdb.set_trace()

In this way, you have to add the debugging instructions in the program you would like to debug, such as the database APIs in our python components, then run your program normally.

For more debugging information, you could refer to the pdb documentation.