[Lldb-commits] [PATCH] D150630: [lldb][docs] Update SB API design document

[Alex Langford via Phabricator via lldb-commits]

bulbazord created this revision.
bulbazord added reviewers: JDevlieghere, jingham, mib, kastiglione.
Herald added a project: All.
bulbazord requested review of this revision.
Herald added a project: LLDB.
Herald added a subscriber: lldb-commits.

The documentation should have been updated in 662548c82683 <https://reviews.llvm.org/rG662548c82683bd8657a3179afee693c4965a3dfd>.
This updates it to be more accurate with the current design.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D150630

Files:
  lldb/docs/design/sbapi.rst


Index: lldb/docs/design/sbapi.rst
===================================================================
--- lldb/docs/design/sbapi.rst
+++ lldb/docs/design/sbapi.rst
@@ -7,6 +7,9 @@
 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 @@
 
 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 different 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
 -------------------


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D150630.522406.patch
Type: text/x-patch
Size: 2483 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20230516/2d51bb18/attachment-0001.bin>