1Scripting Bridge API 2==================== 3 4The SB APIs constitute the stable C++ API that lldb presents to external 5clients, and which get processed by SWIG to produce the Python bindings to 6lldb. As such it is important that they not suffer from the binary 7incompatibilities that C++ is so susceptible to. We've established a few rules 8to ensure that this happens. 9 10The classes in the SB API's are all called SB<SomeName>, where SomeName is in 11CamelCase starting with an upper case letter. The method names are all 12CamelCase with initial capital letter as well. 13 14All the SB API classes are non-virtual, single inheritance classes. They should 15only include SBDefines.h or other SB headers as needed. There should be no 16inlined method implementations in the header files, they should all be in the 17implementation files. And there should be no direct ivar access. 18 19You also need to choose the ivars for the class with care, since you can't add 20or remove ivars without breaking binary compatibility. In some cases, the SB 21class is a thin wrapper around an internal lldb_private object. In that case, 22the class can have a single ivar, which is either a pointer, shared_ptr or 23unique_ptr to the object in the lldb_private API. All the lldb_private classes 24that get used this way are declared as opaque classes in lldb_forward.h, which 25is included in SBDefines.h. So if you need an SB class to wrap an lldb_private 26class that isn't in lldb_forward.h, add it there rather than making a direct 27opaque declaration in the SB classes .h file. 28 29If the SB Class needs some state of its own, as well as the backing object, 30don't include that as a direct ivar in the SB Class. Instead, make an Impl 31class in the SB's .cpp file, and then make the SB object hold a shared or 32unique pointer to the Impl object. The theory behind this is that if you need 33more state in the SB object, those needs are likely to change over time, and 34this way the Impl class can pick up members without changing the size of the 35object. An example of this is the SBValue class. Please note that you should 36not put this Impl class in the lldb namespace. Failure to do so leads to 37leakage of weak-linked symbols in the SBAPI. 38 39In order to fit into the Python API's, we need to be able to default construct 40all the SB objects. Since the ivars of the classes are all pointers of one sort 41or other, this can easily be done, but it means all the methods must be 42prepared to handle their opaque implementation pointer being empty, and doing 43something reasonable. We also always have an "IsValid" method on all the SB 44classes to report whether the object is empty or not. 45 46Another piece of the SB API infrastructure is the Python (or other script 47interpreter) customization. SWIG allows you to add property access, iterators 48and documentation to classes, but to do that you have to use a Swig interface 49file in place of the .h file. Those files have a different format than a 50straight C++ header file. These files are called SB<ClassName>.i, and live in 51"scripts/interface". They are constructed by starting with the associated .h 52file, and adding documentation and the Python decorations, etc. We do this in a 53decidedly low-tech way, by maintaining the two files in parallel. That 54simplifies the build process, but it does mean that if you add a method to the 55C++ API's for an SB class, you have to copy the interface to the .i file. 56 57API Instrumentation 58------------------- 59 60The reproducer infrastructure requires API methods to be instrumented so that 61they can be captured and replayed. Instrumentation consists of two macros, 62``LLDB_REGISTER`` and ``LLDB_RECORD``. Both can be automatically generated with 63the ``lldb-instr`` utility. 64 65To add instrumentation for a given file, pass it to the ``lldb-instr`` tool. 66Like other clang-based tools it requires a compilation database 67(``compile_commands.json``) to be present in the current working directory. 68 69:: 70 71 $ ./bin/lldb-instr /path/to/lldb/source/API/SBDebugger.cpp 72 73 74The tool will automatically insert ``LLDB_RECORD`` macros inline, however you 75will need to run ``clang-format`` over the processed file, as the tool 76(intentionally) makes no attempt to get that right. 77 78The ``LLDB_REGISTER`` macros are printed to standard out between curly braces. 79You'll have to copy-paste those into the corresponding ``RegisterMethods`` 80function in the implementation file. This function is fully specialized in the 81corresponding type. 82 83:: 84 85 template <> void RegisterMethods<SBDebugger>(Registry &R) { 86 ... 87 } 88 89 90When adding a new class, you'll also have to add a call to ``RegisterMethods`` 91in the ``SBRegistry`` constructor. 92 93The tool can be used incrementally. However, it will ignore existing macros 94even if their signature is wrong. It will only generate a ``LLDB_REGISTER`` if 95it emitted a corresponding ``LLDB_RECORD`` macro. 96