debug-pretty-printers

name	debug-pretty-printers
description	Debug and develop GDB and LLDB pretty printers for ezEngine C++ types. Use this skill when working with ezEngine debugger visualizers in ezEngine-gdb.py, ezEngine.py, or ezEngine.natvis. Covers testing with VisualizerZoo.cpp, common errors, and debugging techniques.

Debugging ezEngine Pretty Printers

This skill provides guidance for developing and debugging pretty printers (debugger visualizers) for ezEngine.

File Locations

All pretty printer files are in Code/Engine/Foundation/:

• GDB: Code/Engine/Foundation/ezEngine-gdb.py - Python pretty printers for GDB
• LLDB: Code/Engine/Foundation/ezEngine.py - Python pretty printers for LLDB
• Natvis: Code/Engine/Foundation/ezEngine.natvis - Visual Studio/MSVC visualizers (XML)
• Auto-load: .gdbinit in repository root - Automatically loads GDB printers

Testing with VisualizerZoo.cpp

The primary test file for pretty printers is Code/UnitTests/FoundationTest/CodeUtils/VisualizerZoo.cpp. This file contains test variables for all visualized types organized in EZ_TEST_BLOCK sections.

Finding test sections

Search for EZ_TEST_BLOCK macros to find each section:

grep -n "EZ_TEST_BLOCK" Code/UnitTests/FoundationTest/CodeUtils/VisualizerZoo.cpp

Eac hsection is named descriptively, e.g. EZ_TEST_BLOCK(ezTestBlock::Enabled, "Strings") contains tests for the string types.

Setting breakpoints

Each EZ_TEST_BLOCK section ends with EZ_TEST_BOOL(true); - this is where you should set your breakpoint. At this point, all variables in the block are initialized and in scope.

To find the breakpoint line for a section:

# Find the section start, then look for the EZ_TEST_BOOL(true) before the closing brace
grep -n "EZ_TEST_BLOCK.*Strings" Code/UnitTests/FoundationTest/CodeUtils/VisualizerZoo.cpp
# Then search forward from that line for EZ_TEST_BOOL(true)

Or in an editor, search for EZ_TEST_BLOCK.*SectionName, then find the EZ_TEST_BOOL(true); at the end of that block.

Running the test

First, ensure FoundationTest is built:

cmake --build Workspace/copilot --target FoundationTest

Testing GDB printers in batch mode

Use this exact command pattern to test printers (run from the repository root):

gdb -batch \
  -ex "set pagination off" \
  -ex "source Code/Engine/Foundation/ezEngine-gdb.py" \
  -ex "break VisualizerZoo.cpp:LINE_NUMBER" \
  -ex "run -run -noGui -all" \
  -ex "print variableName" \
  ./Workspace/copilot-output/Bin/LinuxNinjaGccDebug64/FoundationTest

Replace LINE_NUMBER with the line of EZ_TEST_BOOL(true); in the relevant section.

Key points:

• Use timeout 30 prefix if the test might hang
• The breakpoint must be on the EZ_TEST_BOOL(true); line at the END of the block (all variables initialized)
• Add 2>&1 | tail -15 to limit output

Example: Testing string printers

1. Find the Strings section:

   grep -n "EZ_TEST_BLOCK.*Strings" Code/UnitTests/FoundationTest/CodeUtils/VisualizerZoo.cpp
   

2. Find the EZ_TEST_BOOL(true); at the end of that block and note the line number

3. Run GDB with that breakpoint (from repository root):

   gdb -batch \
     -ex "set pagination off" \
     -ex "source Code/Engine/Foundation/ezEngine-gdb.py" \
     -ex "break VisualizerZoo.cpp:101" \
     -ex "run -run -noGui -all" \
     -ex "print string" \
     -ex "print stringView" \
     ./Workspace/copilot-output/Bin/LinuxNinjaGccDebug64/FoundationTest
   

Viewing expanded children

Use set print array on to see children on separate lines:

gdb -batch \
  -ex "set pagination off" \
  -ex "set print array on" \
  -ex "source Code/Engine/Foundation/ezEngine-gdb.py" \
  -ex "break VisualizerZoo.cpp:LINE_NUMBER" \
  -ex "run -run -noGui -all" \
  -ex "print variableName" \
  ./Workspace/copilot-output/Bin/LinuxNinjaGccDebug64/FoundationTest

ezEngine GDB Printer Structure

Registration pattern (from ezEngine-gdb.py)

def build_pretty_printers():
    pp = gdb.printing.RegexpCollectionPrettyPrinter("ezEngine")
    
    # Strings
    pp.add_printer('ezHybridStringBase', r'^ezHybridStringBase<.*>$', ezHybridStringPrinter)
    pp.add_printer('ezStringBuilder', r'^ezStringBuilder$', ezHybridStringPrinter)
    
    # Containers  
    pp.add_printer('ezDynamicArray', r'^ezDynamicArray<.*>$', ezDynamicArrayPrinter)
    
    return pp

gdb.printing.register_pretty_printer(gdb.current_objfile(), build_pretty_printers())

Printer class pattern

class ezMyTypePrinter:
    def __init__(self, val):
        self.val = val

    def to_string(self):
        """Return the display string for the value."""
        try:
            return f"{{ count={count} }}"
        except Exception as e:
            return f"<error: {e}>"

    def children(self):
        """Yield (name, value) tuples for expandable children."""
        try:
            yield 'm_uiCount', self.val['m_uiCount']
            yield 'm_pAllocator', self.val['m_pAllocator']
            for i in range(count):
                yield f'[{i}]', (m_pElements + i).dereference()
        except Exception as e:
            yield 'error', str(e)

    def display_hint(self):
        return 'array'  # or 'string' or 'map'

Common Errors and Solutions

"Type is not a template"

Problem: Calling val.type.template_argument(0) on ezStringBuilder (not a template).

Solution: Get size from the actual member instead:

# Instead of: local_storage_size = val.type.template_argument(0)
local_storage_size = m_Data['m_StaticData'].type.sizeof

"Trying to read string with inappropriate type"

Problem: Calling .string() on array address instead of char*.

Solution: Cast to char* first:

char_ptr_type = gdb.lookup_type('char').pointer()
ptr = m_Data['m_StaticData'].address.cast(char_ptr_type)
result = ptr.string(length=count)

"There is no member named X"

Problem: Wrong member name. Check the LLDB or Natvis implementation for correct names.

Solution: Use GDB to inspect the actual type:

gdb -batch -ex "ptype ezHashedString" ./Output/Bin/LinuxNinjaGccDebug64/FoundationTest

Children showing as strings instead of expandable values

Problem: Yielding formatted strings in children() instead of GDB values.

Solution: Yield actual GDB values that have their own printers:

# Wrong - yields a string, not expandable
yield 'c0', f"{{ x={x}, y={y}, z={z} }}"

# Correct - yields the actual value, GDB will use ezVec3Printer on it
yield 'c0', elements[0].address.cast(vec3_type.pointer()).dereference()

ezHybridString inline vs heap storage

The ezHybridStringBase uses inline storage (m_StaticData) when capacity fits, otherwise heap (m_pElements):

def _get_string_data(self):
    m_Data = self.val['m_Data']
    m_uiCount = int(m_Data['m_uiCount'])
    m_uiCapacity = int(m_Data['m_uiCapacity'])
    local_storage_size = m_Data['m_StaticData'].type.sizeof

    if m_uiCapacity <= local_storage_size:
        # Using inline storage
        char_ptr_type = gdb.lookup_type('char').pointer()
        ptr = m_Data['m_StaticData'].address.cast(char_ptr_type)
    else:
        # Using heap storage
        ptr = m_Data['m_pElements']

    return ptr, m_uiCount

Template type lookup for math types

To cast array elements to vector types (e.g., for ezMat3 columns):

elements = self.val['m_fElementsCM']
elem_type = elements[0].type
vec3_type = gdb.lookup_type(f'ezVec3Template<{elem_type}>')
col0 = elements[0].address.cast(vec3_type.pointer()).dereference()

LLDB Comparison

When implementing GDB printers, reference the LLDB implementation in ezEngine.py:

• LLDB uses set_fields(['m_uiCount', 'm_uiCapacity', 'm_pAllocator']) to add member children
• GDB equivalent: yield each field in children() before array elements
• LLDB GetChildMemberWithName('m_Data') → GDB self.val['m_Data']
• LLDB GetValueAsUnsigned(0) → GDB int(self.val['m_Member'])

Debugging Workflow

1. Identify the type: Check which printer handles it in build_pretty_printers()
2. Find test variable: Look in VisualizerZoo.cpp for a variable of that type
3. Set breakpoint after initialization: Use the table above for correct line numbers
4. Test to_string() first: Get the display string working before children()
5. Add children() incrementally: Test each child field separately
6. Compare with LLDB/Natvis: Use existing implementations as reference for member names

Auto-loading

The .gdbinit file in the repository root automatically loads the printers when debugging in the ezEngine directory. It uses path detection relative to the current working directory.