GDB pretty printers
reloco ships GDB pretty printers for its containers, views, and smart
pointers, so print/display show readable values (reloco::vector of
length 3, capacity 8 = {10, 20, 30}) instead of raw struct dumps of
internal data_/size_/cap_ fields.
The printers live in one place, tools/gdb/reloco_printers.py, and are
usable in three interchangeable ways.
1. Source it directly in a running GDB session
(gdb) source /path/to/reloco/tools/gdb/reloco_printers.py
Useful for a one-off debugging session without touching the target binary or your GDB configuration.
2. Auto-load it for a specific binary
Place a <binary>-gdb.py file next to your executable (or anywhere on
GDB’s auto-load path) containing:
import sys
sys.path.insert(0, "/path/to/reloco/tools/gdb")
import reloco_printers
reloco_printers.register_reloco_printers()
GDB loads this automatically whenever it loads a matching binary (subject
to auto-load safe-path, see below).
3. Embed it directly into the binary (no external files)
#include <reloco/gdb_printers.hpp>
Including this header anywhere in your program (typically once, from the
translation unit containing main) embeds the entire contents of
tools/gdb/reloco_printers.py into a .debug_gdb_scripts ELF/COFF
section via inline assembly, using GDB’s “Python text” section-script
mechanism.
When GDB loads the resulting binary, it automatically extracts and runs
that exact script, registering the printers – no source command, no
<binary>-gdb.py file, and no sys.path setup required on the machine
doing the debugging. This is the recommended option for shipping printers
alongside a distributable binary or a project’s own test executables.
This header is opt-in only: it is not included by any other reloco header,
is not part of tests/compile_all_headers.cpp’s default header-compile
check, and adds no cost unless you explicitly #include it. It is also
deliberately excluded from automated cross-compiler testing/CI: the
.debug_gdb_scripts embedding relies on GNU-assembler inline asm syntax
that has no equivalent on MSVC (or other compilers without GNU inline-asm
support), so the header guards its body on defined(__clang__) ||
defined(__GNUC__) and is a silent no-op elsewhere – there is nothing
portable to verify by including it by default.
include/reloco/gdb_printers.hpp is generated by
tools/gdb/generate_embedded_header.py from reloco_printers.py and
should never be hand-edited; regenerate it after changing the printer
script:
python3 tools/gdb/generate_embedded_header.py
auto-load safe-path
Both option 2 and option 3 are subject to GDB’s auto-load safe-path
security setting, which by default only trusts scripts from a small set of
system locations. If GDB declines to load the printers, either add the
binary’s directory:
(gdb) add-auto-load-safe-path /path/to/binary/dir
or add it permanently to ~/.gdbinit. See the Auto-loading safe
path
section of the GDB manual for details.
Coverage
Printers are registered for: array, span, vector, inline_vector,
sso_vector, flat_set, flat_map, inline_flat_set, inline_flat_map,
sso_flat_set, sso_flat_map,
basic_string/basic_string_view/basic_inline_string/basic_sso_string,
optional, expected (including the void specialization), unique_ptr,
shared_ptr/weak_ptr (showing use_count/weak_count), rc/weak_rc
(same, but with plain non-atomic counts), value_ptr, value_ref,
checked_value, cell, ref_cell (showing its borrow state), non_zero,
wrapping, saturating, checked,
binary_heap, cow (showing owned-vs-borrowed state), boxed_slice,
guarded_mutex, function_ref, type_id, and any.
type_id’s printer shows its registered debug name (see
RELOCO_TYPE_ID_NAME in type_id.hpp) when one is present, or [unnamed]
with the raw tag address otherwise, and [none] for a default-constructed
sentinel type_id. any’s printer reuses this: since reloco uses no RTTI
anywhere, the held value’s concrete type is genuinely erased, so the
printer can only report whether any is empty and, if not, the held
type’s registered debug name (if any) – it never attempts to read or
format the held value itself, which (like collection_view/container_ref
below) would require calling through the private vtable’s function
pointers from Python.
collection_view/container_ref (the type-erased container views) are
deliberately not covered: printing their size requires calling through
a vtable function pointer stored in the target process, which is fragile
across GDB versions and unavailable when inspecting a core file, so the
default struct dump is left as-is for those types.
Regenerating and testing
After editing tools/gdb/reloco_printers.py:
- Regenerate the embedded header:
python3 tools/gdb/generate_embedded_header.py. - Add or update a test case for the changed/new type in
tools/gdb/testbed/and runtools/gdb/testbed/run.sh, which compiles a real program using the printers and checks their output under GDB in all three loading modes above. Seetools/gdb/testbed/README.mdfor how to add a case; that testbed is not part of the main build/CI, so it must be run explicitly.