[Lldb-commits] [lldb] ec388ad - [lldb][docs] Update SB API design document

[Alex Langford via lldb-commits]

Author: Alex Langford
Date: 2023-05-16T12:58:54-07:00
New Revision: ec388adbbcbf2cf7f2743464ef5b3c5c540a2d23

URL: https://github.com/llvm/llvm-project/commit/ec388adbbcbf2cf7f2743464ef5b3c5c540a2d23
DIFF: https://github.com/llvm/llvm-project/commit/ec388adbbcbf2cf7f2743464ef5b3c5c540a2d23.diff

LOG: [lldb][docs] Update SB API design document

The documentation should have been updated in 662548c82683.
This updates it to be more accurate with the current design.

Differential Revision: https://reviews.llvm.org/D150630

Added: 
    

Modified: 
    lldb/docs/design/sbapi.rst

Removed: 
    


################################################################################
diff  --git a/lldb/docs/design/sbapi.rst b/lldb/docs/design/sbapi.rst
index f4a7ca271be63..f2de0e7ae60ca 100644
--- a/lldb/docs/design/sbapi.rst
+++ b/lldb/docs/design/sbapi.rst
@@ -7,6 +7,9 @@ lldb. As such it is important that they not suffer from the binary
 incompatibilities that C++ is so susceptible to. We've established a few rules
 to ensure that this happens.
 
+Extending the SB API
+--------------------
+
 The classes in the SB API's are all called SB<SomeName>, where SomeName is in
 CamelCase starting with an upper case letter. The method names are all
 CamelCase with initial capital letter as well.
@@ -45,14 +48,29 @@ classes to report whether the object is empty or not.
 
 Another piece of the SB API infrastructure is the Python (or other script
 interpreter) customization. SWIG allows you to add property access, iterators
-and documentation to classes, but to do that you have to use a Swig interface
-file in place of the .h file. Those files have a 
diff erent format than a
-straight C++ header file. These files are called SB<ClassName>.i, and live in
-"scripts/interface". They are constructed by starting with the associated .h
-file, and adding documentation and the Python decorations, etc. We do this in a
-decidedly low-tech way, by maintaining the two files in parallel. That
-simplifies the build process, but it does mean that if you add a method to the
-C++ API's for an SB class, you have to copy the interface to the .i file.
+and documentation to classes. We place the property accessors and iterators in
+a file dedicated to extensions to existing SB classes at
+"bindings/interface/SB<ClassName>Extensions.i". The documentation is similarly
+located at "bindings/interface/SB<ClassName>Docstrings.i". These two files, in
+addition to the actual header SB<ClassName>.h, forms the interface that lldb
+exposes to users through the scripting languages.
+
+There are some situations where you may want to add functionality to the SB API
+only for use in C++. To prevent SWIG from generating bindings to these
+functions, you can use a C macro guard, like so:
+
+::
+
+  #ifndef SWIG
+  int GetResourceCPPOnly() const;
+  #endif
+
+In this case, ``GetResourceCPPOnly`` will not be generated for Python or other
+scripting languages. If you wanted to add a resource specifically only for the
+SWIG case, you can invert the condition and use ``#ifdef SWIG`` instead. When
+building the LLDB framework for macOS, the headers are processed with
+``unifdef`` prior to being copied into the framework bundle to remove macros
+involving SWIG.
 
 API Instrumentation
 -------------------