eepp/projects/scripts/debug

eepp Debugger Scripts

This directory contains Python scripts for GDB and LLDB to make debugging the eepp framework easier.

Specifically, these scripts provide "pretty-printers" for custom, highly-optimized data structures like EE::SmallVector. Because EE::SmallVector uses advanced bit-packing and tagged pointers to minimize stack overhead, it can look like unreadable memory in a raw debugger. These scripts unmask the data so it reads exactly like a standard std::vector.

GDB (GNU Debugger)

To make GDB automatically format EE::SmallVector objects, you need to load the eepp_gdb.py script.

Option 1: Auto-Load for all eepp projects (Recommended)

Add the following line to your ~/.gdbinit file to load the pretty-printers automatically every time you start GDB. Make sure to replace /path/to/eepp with your actual local path:

python exec(open("/path/to/eepp/projects/scripts/debug/eepp_gdb.py").read())

Option 2: Manual Load (Per Session)

If you only want to load it for a specific debugging session, run this command inside the GDB prompt:

(gdb) source /path/to/eepp/projects/scripts/debug/eepp_gdb.py

LLDB (Clang)

LLDB uses a different Python API for formatting variables. Use the eepp_lldb.py script to get clean summaries and expandable array elements.

Option 1: Auto-Load for all eepp projects (Recommended)

Add this line to your ~/.lldbinit file so LLDB automatically imports the formatting rules:

command script import /path/to/eepp/projects/scripts/debug/eepp_lldb.py

Option 2: Manual Load (Per Session)

To load the script manually while LLDB is running, use this command in the LLDB prompt:

(lldb) command script import /path/to/eepp/projects/scripts/debug/eepp_lldb.py

Verification

Once loaded, an EE::SmallVector containing elements will display cleanly in your watch window or terminal output:

Without the script:

clientsCopy = { m_data = { _M_elems = "\x07\x00\x00..." } }

With the script:

clientsCopy = [Direct] size=3

[0] = 0x00007fffffff1230

[1] = 0x00007fffffff1280

[2] = 0x00007fffffff12a0