lldb/docs/resources/sbapi.rst

   1 Scripting Bridge API
   2 ====================
   3
   4 The SB APIs constitute the stable C++ API that lldb presents to external
   5 clients, and which get processed by SWIG to produce the Python bindings to
   6 lldb. As such it is important that they not suffer from the binary
   7 incompatibilities that C++ is so susceptible to. We've established a few rules
   8 to ensure that this happens.
   9
  10 Extending the SB API
  11 --------------------
  12
  13 The classes in the SB API's are all called SB<SomeName>, where SomeName is in
  14 CamelCase starting with an upper case letter. The method names are all
  15 CamelCase with initial capital letter as well.
  16
  17 All the SB API classes are non-virtual, single inheritance classes. They should
  18 only include SBDefines.h or other SB headers as needed. There should be no
  19 inlined method implementations in the header files, they should all be in the
  20 implementation files. And there should be no direct ivar access.
  21
  22 You also need to choose the ivars for the class with care, since you can't add
  23 or remove ivars without breaking binary compatibility. In some cases, the SB
  24 class is a thin wrapper around an internal lldb_private object. In that case,
  25 the class can have a single ivar, which is either a pointer, shared_ptr or
  26 unique_ptr to the object in the lldb_private API. All the lldb_private classes
  27 that get used this way are declared as opaque classes in lldb_forward.h, which
  28 is included in SBDefines.h. So if you need an SB class to wrap an lldb_private
  29 class that isn't in lldb_forward.h, add it there rather than making a direct
  30 opaque declaration in the SB classes .h file.
  31
  32 If the SB Class needs some state of its own, as well as the backing object,
  33 don't include that as a direct ivar in the SB Class. Instead, make an Impl
  34 class in the SB's .cpp file, and then make the SB object hold a shared or
  35 unique pointer to the Impl object. The theory behind this is that if you need
  36 more state in the SB object, those needs are likely to change over time, and
  37 this way the Impl class can pick up members without changing the size of the
  38 object. An example of this is the SBValue class. Please note that you should
  39 not put this Impl class in the lldb namespace. Failure to do so leads to
  40 leakage of weak-linked symbols in the SBAPI.
  41
  42 In order to fit into the Python API's, we need to be able to default construct
  43 all the SB objects. Since the ivars of the classes are all pointers of one sort
  44 or other, this can easily be done, but it means all the methods must be
  45 prepared to handle their opaque implementation pointer being empty, and doing
  46 something reasonable. We also always have an "IsValid" method on all the SB
  47 classes to report whether the object is empty or not.
  48
  49 Another piece of the SB API infrastructure is the Python (or other script
  50 interpreter) customization. SWIG allows you to add property access, iterators
  51 and documentation to classes. We place the property accessors and iterators in
  52 a file dedicated to extensions to existing SB classes at
  53 "bindings/interface/SB<ClassName>Extensions.i". The documentation is similarly
  54 located at "bindings/interface/SB<ClassName>Docstrings.i". These two files, in
  55 addition to the actual header SB<ClassName>.h, forms the interface that lldb
  56 exposes to users through the scripting languages.
  57
  58 There are some situations where you may want to add functionality to the SB API
  59 only for use in C++. To prevent SWIG from generating bindings to these
  60 functions, you can use a C macro guard, like so:
  61
  62 ::
  63
  64   #ifndef SWIG
  65   int GetResourceCPPOnly() const;
  66   #endif
  67
  68 In this case, ``GetResourceCPPOnly`` will not be generated for Python or other
  69 scripting languages. If you wanted to add a resource specifically only for the
  70 SWIG case, you can invert the condition and use ``#ifdef SWIG`` instead. When
  71 building the LLDB framework for macOS, the headers are processed with
  72 ``unifdef`` prior to being copied into the framework bundle to remove macros
  73 involving SWIG.
  74
  75 Lifetime
  76 --------
  77 Many SB API methods will return strings in the form of ``const char *`` values.
  78 Once created, these strings are guaranteed to live until the end of the
  79 debugging session. LLDB owns these strings, clients should not attempt to free
  80 them. Doing so may cause LLDB to crash.
  81 Note that this only affects the C++ API as scripting languages usually
  82 will usually create native string types from the ``const char *`` value.
  83
  84 API Instrumentation
  85 -------------------
  86
  87 The reproducer infrastructure requires API methods to be instrumented so that
  88 they can be captured and replayed. Instrumentation consists of two macros,
  89 ``LLDB_REGISTER`` and ``LLDB_RECORD``. Both can be automatically generated with
  90 the ``lldb-instr`` utility.
  91
  92 To add instrumentation for a given file, pass it to the ``lldb-instr`` tool.
  93 Like other clang-based tools it requires a compilation database
  94 (``compile_commands.json``) to be present in the current working directory.
  95
  96 ::
  97
  98    $ ./bin/lldb-instr /path/to/lldb/source/API/SBDebugger.cpp
  99
 100
 101 The tool will automatically insert ``LLDB_RECORD`` macros inline, however you
 102 will need to run ``clang-format`` over the processed file, as the tool
 103 (intentionally) makes no attempt to get that right.
 104
 105 The ``LLDB_REGISTER`` macros are printed to standard out between curly braces.
 106 You'll have to copy-paste those into the corresponding ``RegisterMethods``
 107 function in the implementation file. This function is fully specialized in the
 108 corresponding type.
 109
 110 ::
 111
 112   template <> void RegisterMethods<SBDebugger>(Registry &R) {
 113     ...
 114   }
 115
 116
 117 When adding a new class, you'll also have to add a call to ``RegisterMethods``
 118 in the ``SBRegistry`` constructor.
 119
 120 The tool can be used incrementally. However, it will ignore existing macros
 121 even if their signature is wrong. It will only generate a ``LLDB_REGISTER`` if
 122 it emitted a corresponding ``LLDB_RECORD`` macro.