Custom Data Formatters

So, you want to create custom data formatters for your favorite library or a programming language?

Here's how I recommend going about it:

• Familiarize yourself with the options LLDB provides.
• Decide what level of customization your data types require.
  For many types, declarative type summary strings and type filters are quite adequate. If these fit you needs:
  • Create a file containing LLDB commands that create your customizations.
  • Load it via command source <file path> command, which can be added to initCommands launch target property in launch.json, or to lldb.launch.initCommands property in workspace or global settings.
    For example, "initCommands": ["command source '${workspaceFolder}/my_type_formatters'"].
  • Examples: [1], [2].
• Otherwise, you'll need to do some Python scripting.
  • Create a new Python module containing:
    • Functions for scripted summaries,
    • Classes implementing the synthetic children provider interface,
    • __lldb_init_module(debugger, internal_dict) function, that will be called by LLDB upon importing the module.
      Here, you will need to:
      • Create a type category object, which serves as a container of individual type formatters and allows turning them on or off all at the same time.
      • Register your type summaries and synthetic providers.
    • Load it via command script import <file path>.
  • Resources:
    • LLDB Python API. These classes will be most relevant for your task:
      • SBValue, which is how LLDB represents variables and expression evaluation results,
      • SBType, which represents types in your program,
      • SBData, which can be used to read the raw contents of an SBValue,
      • SBProcess, which represents the process being debugged and can be used to read raw bytes from the process memory,
      • SBTypeCategory, which represents type categories,
      • SBTypeNameSpecifier, which allows selecting what types a particular summary or synthetic applies to,
      • SBTypeSummary, which wraps functions implementing type summaries,
      • SBTypeSynthetic, same for type synthetics.
    • Examples of type summaries.
    • Examples of type synthetics.