jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Start adding C++ wrappers generation

Browse source 
Disable them for the test suite, as plenty things don't work yet, but
there is already more than enough code to not want to add even more
fixes to the same commit.
This commit is contained in:
Vadim Zeitlin 2021-11-16 23:36:02 +01:00
commit 0483e4017c
3 changed files with 621 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

25
Doc/Manual/C.html
View file

@ -28,6 +28,7 @@
<li><a href="#C_classes">Classes</a>
</ul>
<li><a href="#C_exceptions">Exception handling</a>
<li><a href="#C_cxx_wrappers">C++ wrappers</a>
</ul>
</div>
<!-- INDEX -->
@ -58,7 +59,7 @@ With wrapper interfaces generated by SWIG, it is easy to use the functionality o
</p>
<p>
Flattening C++ language constructs into a set of C-style functions obviously comes with many limitations and inconveniences. All data and functions become global. Manipulating objects requires explicit calls to special functions. We are losing the high level abstraction and have to work around it.
Flattening C++ language constructs into a set of C-style functions obviously comes with many limitations and inconveniences, but this module is actually also capable of generating C++ wrappers defined completely inline using the C functions, thus wrapping the original C++ library API in another, similar C++ API. Contrary to the natural initial reaction, this is far from being completely pointless, as wrapping C++ API in this way avoids all problems due to C++ ABI issues, e.g. it is now possible to use the original C++ API using a different C++ compiler, or a different version of the same compiler, or even the same compiler, but with different compilation options affecting the ABI. The C++ wrapper API is not identical to the original one, but strives to be as close to it as possible.
</p>
<H3>Known C++ Shortcomings in Generated C API:</H3>
@ -137,6 +138,11 @@ $ swig -c -help
<td>Generate wrappers with the prefix based on the provided namespace, e.g. if the option value is <tt>outer::inner</tt>, the prefix <tt>outer_inner_</tt> will be used. Notice that this is different from using SWIG <tt>nspace</tt> feature, as it applies the the prefix to all the symbols, regardless of the namespace they were actually declared in. Notably, this allows to export instantiations of templates defined in the <tt>std</tt> namespace, such as <tt>std::vector</tt>, using a custom prefix rather than <tt>std_</tt>.</td>
</tr>
<tr>
<td>-nocxx</td>
<td>Don't generate C++ wrappers, even when <tt>-c++</tt> option is used. See <a href="#C_cxx_wrappers">C++ Wrappers</a> section for more details.</td>
</tr>
<tr>
<td>-noexcept</td>
<td>generate wrappers with no support of exception handling; see <a href="#C_exceptions">Exceptions</a> chapter for more details </td>
@ -643,6 +649,23 @@ void SomeIntTemplateClass_delete(SomeIntTemplateClass * carg1);
<H2><a name="C_exceptions"></a>36.5 Exception handling</H2>
<H2><a name="C_cxx_wrappers"></a>36.6 C++ Wrappers</H2>
<p>
When <tt>-c++</tt> command line option is used (and <tt>-nocxx</tt> one is not), the header file generated by SWIG will also contain the declarations of C++ wrapper functions and classes mirroring the original API. All C++ wrappers are fully inline, i.e. don't need to be compiled separately, and are always defined inside the namespace (or nested namespaces) specified by <tt>-namespace</tt> command-line option or the namespace with the same name as the SWIG module name if this option is not specified.
</p>
<p>
C++ wrappers try to provide a similar API to the original C++ API being wrapped, notably any class <tt>Foo</tt> in the original API appears as a class with the same name in the wrappers namespace, and has the same, or similar, public methods. A class <tt>Bar</tt> deriving from <tt>Foo</tt> also derives from it in the wrappers and so on. There are some differences with the original API, however. Some of them are due to fundamental limitations of the approach used, e.g.:
<ul>
<li>Only template instantiations are present in the wrappers, not the templates themselves.</li>
</ul>
Other ones are due to things that could be supported but haven't been implemented yet:
<ul>
<li>Only single, not multiple, inheritance is currently supported.</li>
</ul>
</p>
</body>
</html>