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:

  1. Regenerate the embedded header: python3 tools/gdb/generate_embedded_header.py.
  2. Add or update a test case for the changed/new type in tools/gdb/testbed/ and run tools/gdb/testbed/run.sh, which compiles a real program using the printers and checks their output under GDB in all three loading modes above. See tools/gdb/testbed/README.md for how to add a case; that testbed is not part of the main build/CI, so it must be run explicitly.