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 -------------------
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 -------------------
_______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
