Where is the documentation for Xcode's Edit Summary Format functionality?

Question

If I add an expression to the left-hand panel of the Xcode debugger, from the popup menu for it I can select an option marked Edit Summary Format....

This brings up a popover saying Set Summary Format for type XXX, where XXX is the type of the expression.

The closest to documentation for this functionality I've found is in the Xcode help, View variables in the debug area page, View variables section:

To edit the summary format of a variable ... In the popover, enter a valid LLDB expression and click Done. This expression overrides the default formatter and is used to create a summary for all variables of this type.

OK, but the popover's placeholder text mentions $VAR, which appears to be a valid thing to enter in the summary format - but lldb doesn't accept this! So I'm suspicious this bit of documentation, such as it is, isn't actually accurate.

Where is the rest of the documentation for this feature?

Answer 1

That summary format was invented back when Xcode used gdb as its debugger, and before gdb had any built-in support for data formatters. It was only ever understood by Xcode, and is maintained mostly for legacy reasons.

Xcode no longer supports gdb, using lldb instead. lldb has it's own data formatter system:

https://lldb.llvm.org/varformats.html

It has the advantage that it will apply to Xcode's Variables view, to any commands you write using lldb's SB API, and to all the lldb command line commands that present values (e.g. expr, frame var).

You can define formatters as described in the link above in your ~/.lldbinit file, and they will apply both to Xcode debugging sessions and to command-line lldb sessions (should you have reason to use command-line lldb.) For ease of maintenance I make a .lldb directory, put my formatters in a file like formatters.lldb there, and then in my .lldbinit, do:

command source ~/.lldb/formatters.lldb

That way when I'm working on them I can independently source in the formatters, without having to worry about what else the .lldbinit is doing.