Debugging with GDB

PIP ships a GDB pretty-printer script, tools/gdb/pip_pp.py, that makes the basic types print their content instead of their raw internals:

Type	Example output
PIString	"hello"
PIByteArray	{0x48, 0x65, 0x6c, 0x6c, 0x6f}
PIChar	'a' or U+043c
PIVector<T>	{1, 2, 3}
PIDeque<T>	{1, 2, 3}
PIStringList	{"one", "two"}
PIMap<K,V>	{"x": 1, "y": 2}
PISet<T>	{3, 5}
PIPair<K,V>	{"k", 7}
PIVariant	PIVariant(pivInt, 4 bytes)
PINetworkAddress	192.168.1.10:8080

Nested containers are printed recursively, e.g. PIVector<PIString> prints as {"a", "bb"}. Pointers to the covered types show the address and the content: (PIString *) 0x7fffffffdac0 "hello".

Printers are read-only and defensive: on any error GDB falls back to the default (raw) printing. Long containers are truncated, only the first 32 elements are printed by default (the tail is shown as ..., ... (N total)); the limit is the _MAX_ELEMENTS constant at the top of pip_pp.py.

Requirements: the executable and the PIP library must be built with debug information (-g).

Loading the pretty-printers

Manual (works with any build tree):

(gdb) source /path/to/pip/tools/gdb/pip_pp.py

Run it after the executable is loaded (in a session started as gdb ./program, or after the file command).

Automatic: CMake install places the script at <prefix>/share/pip/gdb/pip_pp.py and an auto-load stub <prefix>/lib/libpip.so-gdb.py next to the library. GDB evaluates the stub automatically when libpip.so is loaded (see GDB manual, "Auto-loading extensions"). If the library is installed outside of GDB's default auto-load safe path, add the directory once:

(gdb) add-auto-load-safe-path /your/prefix/lib

Or create <homedir>/.gdbinit file and write to it next line

add-auto-load-safe-path <root_dir>

, where root_dir is top-level directory contains library and pip_pp.py script.

The stub is installed only for shared builds; for static builds use the manual source command.

Qt Creator

Qt Creator's Variables/Expressions views do not use GDB pretty-printers; they run their own Python dumper. PIP provides the dumper module tools/qtcreator/pip_types.py, which covers the same types as pip_pp.py. To enable it:

1. Open the debugger settings (Qt Creator -> Settings -> Debugger).
2. Switch to the "Variables and expressions" tab.
3. In the "Extra dumper file" field (tooltip: "Path to a Python file containing additional data dumpers"), enter the path to the file:

/path/to/pip/tools/qtcreator/pip_types.py

After that PIString, PIVector<T>, PIMap<K,V> and the other types from the table above show their content in the Variables/Expressions views. No changes to the GDB setup (.gdbinit, auto-load stub) are needed for Qt Creator; those keep working for the command-line GDB.

Verifying the installation

A check script builds a demo with all covered types and asserts the expected GDB output:

tools/gdb/test/test_pp.sh build_linux