Debugging STL objects in GDB

gdb_inspecting_stl_containers.md

Original: https://github.com/NREL/EnergyPlus/wiki/Debugging-STL-objects-in-GDB

Overview

This documents how to add STL visualizer support in gdb. This information was pulled together from a variety of sources on the web to ultimately get it working well. Without these pretty printers, you get some details (that might be interesting sometimes) like:

(gdb) print foo_int_vector
$1 = {<std::_Vector_base<int, std::allocator<int> >> = {_M_impl = {<std::allocator<int>> = {<__gnu_cxx::new_allocator<int>> = {<No data fields>}, <No data fields>}, _M_start = 0x603010, _M_finish = 0x60301c, 
      _M_end_of_storage = 0x60301c}}, <No data fields>}

Some notes:

• Gdb uses python 3.x.
• You can't import gdb in a standalone python session, only when called from gdb.

Getting the pretty printers themselves:

• If you can, just checkout the relevant folder in the repo: svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python.
• if you can't, just pull the whole file structure, file-by-file, from here: https://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python/.
• Either way, you should end up with a folder structure like: /path/to/gdb/python/libstdcxx/v6/printers.py.

Modifying the pretty printer folder:

• Since Python will be importing from the root python folder, I put an empty __init__.py folder in there; maybe its not needed, but it didn't hurt.

Telling gdb where to find said printers:

• Modify the ~/.gdbinit file with the following snippet -- change the path to match above.

python
import sys
sys.path.insert(0, '/path/to/gdb/python')
from libstdcxx.v6.printers import register_libstdcxx_printers
#register_libstdcxx_printers (None)
end

• Line 1 tells gdb we are starting a python snippet.
• Line 2 imports the python sys library so we can modify the path.
• Line 3 adds the root of the repo checkout above.
• Line 4 expects to find a script at the relative path .../libstdcxx/v6/printers.py on the path...which it will find inside the path we added in line 3.
• Line 5 was recommended originally in forums, but taken out because they are already registered upon import.
• Line 6 tells gdb we are done with this snippet.

Using it

Now when you open gdb, you should be able to debug vectors easily. Consider the following program, in a file named vectors.cpp:

#include <vector>
int main() {
    std::vector<int> ints;
    ints.push_back(2);
    ints.push_back(0);
    return 0;
}

Build it with debugging available:

$ g++ -g -O0 vectors.cpp

Head into gdb and break at that line:

$ gdb a.out
(gdb) break vectors.cpp:6
(gdb) run
Breakpoint 1, main () at vectors.cpp:6
(gdb) print ints 
$1 = std::vector of length 2, capacity 2 = {2, 0}

w00t.