mirror of https://github.com/swig/swig
177 lines
7.4 KiB
HTML
177 lines
7.4 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Working with Modules</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="Modules"></a>15 Working with Modules</H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Modules_nn2">The SWIG runtime code</a>
|
|
<li><a href="#external_run_time">External access to the runtime</a>
|
|
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
|
|
<li><a href="#Modules_nn5">References</a>
|
|
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
|
|
</ul>
|
|
</div>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
When first working with SWIG, users commonly start by creating a
|
|
single module. That is, you might define a single SWIG interface that
|
|
wraps some set of C/C++ code. You then compile all of the generated
|
|
wrapper code into a module and use it. For large applications, however,
|
|
this approach is problematic---the size of the generated wrapper code
|
|
can be rather large. Moreover, it is probably easier to manage the
|
|
target language interface when it is broken up into smaller pieces.
|
|
</p>
|
|
|
|
<p>
|
|
This chapter describes the problem of using SWIG in programs
|
|
where you want to create a collection of modules.
|
|
</p>
|
|
|
|
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
|
|
|
|
|
|
<p>
|
|
Many of SWIG's target languages generate a set of functions
|
|
commonly known as the "SWIG runtime." These functions are
|
|
primarily related to the runtime type system which checks pointer
|
|
types and performs other tasks such as proper casting of pointer
|
|
values in C++. As a general rule, the statically typed target languages,
|
|
such as Java, use the language's built in static type checking and
|
|
have no need for a SWIG runtime. All the dynamically typed / interpreted
|
|
languages rely on the SWIG runtime.
|
|
</p>
|
|
|
|
<p>
|
|
The runtime functions are private to each SWIG-generated
|
|
module. That is, the runtime functions are declared with "static"
|
|
linkage and are visible only to the wrapper functions defined in that
|
|
module. The only problem with this approach is that when more than one SWIG
|
|
module is used in the same application, those modules often need to
|
|
share type information. This is especially true for C++ programs
|
|
where SWIG must collect and share information about inheritance
|
|
relationships that cross module boundaries.
|
|
</p>
|
|
|
|
<p>
|
|
To solve the problem of sharing information across modules, a pointer to the
|
|
type information is stored in a global variable in the target language namespace.
|
|
During module initialization, type information is loaded into the global data
|
|
structure of type information from all modules.
|
|
</p>
|
|
|
|
<p>
|
|
This can present a problem with threads. If two modules try and load at the same
|
|
time, the type information can become corrupt. SWIG currently does not provide any
|
|
locking, and if you use threads, you must make sure that modules are loaded serially.
|
|
Be careful if you use threads and the automatic module loading that some scripting
|
|
languages provide. One solution is to load all modules before spawning any threads.
|
|
</p>
|
|
|
|
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
|
|
|
|
|
|
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
|
|
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
|
|
to be called. Calling these functions from a typemap is supported, since the typemap code
|
|
is embedded into the <tt>_wrap.c</tt> file, which has those declerations available. If you need
|
|
to call the SWIG run-time functions from another C file, there is one header you need
|
|
to include. To generate the header that needs to be included, run the following command:
|
|
|
|
<div class="code"><pre>
|
|
$ swig -python -external-runtime <filename>
|
|
</pre></div>
|
|
|
|
<p>The filename argument is optional and if it is not passed, then the default filename will
|
|
be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should
|
|
be treated like any of the other _wrap.c output files, and should be regenerated when the
|
|
_wrap files are. After including this header, your code will be able to call <tt>SWIG_TypeQuery</tt>,
|
|
<tt>SWIG_NewPointerObj</tt>, <tt>SWIG_ConvertPtr</tt> and others. The exact argument paramaters
|
|
for these functions might differ between language modules; please check the language module chapters
|
|
for more information.</p>
|
|
|
|
<p>Inside this header the functions are declared static and are included inline into the file,
|
|
and thus the file does not need to be linked against any SWIG libraries or code (you might still
|
|
need to link against the language libraries like libpython-2.3). Data is shared between this
|
|
file and the _wrap.c files through a global variable in the scripting language. It is also
|
|
possible to copy this header file along with the generated wrapper files into your own package,
|
|
so that you can distribute a package that can be compiled without SWIG installed (this works
|
|
because the header file is self contained, and does not need to link with anything).</p>
|
|
|
|
<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2>
|
|
|
|
|
|
<p>
|
|
When working with multiple SWIG modules, you should take care not to use static
|
|
libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
|
|
of SWIG modules with that library, each module will get its own private copy of the library code inserted
|
|
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
|
|
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
|
|
</p>
|
|
|
|
<H2><a name="Modules_nn5"></a>15.4 References</H2>
|
|
|
|
|
|
<p>
|
|
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
|
|
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
|
|
</p>
|
|
|
|
<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2>
|
|
|
|
|
|
<p>
|
|
Using multiple modules with the <tt>%import</tt> directive is the most common approach to modularising large projects.
|
|
In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file.
|
|
There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
|
|
</p>
|
|
|
|
<p>
|
|
<b>-fcompact</b><br>
|
|
This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
|
|
It simply removes blank lines and joins lines of code together.
|
|
This is useful for compilers that have a maximum file size that can be handled.
|
|
</p>
|
|
|
|
<p>
|
|
<b>-fvirtual</b><br>
|
|
This command line option will remove the generation of superfluous virtual method wrappers.
|
|
Consider the following inheritance hierarchy:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
struct Base {
|
|
virtual void method();
|
|
...
|
|
};
|
|
|
|
struct Derived : Base {
|
|
virtual void method();
|
|
...
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
|
|
Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
|
|
a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
<b>%feature("compactdefaultargs")</b><br>
|
|
This feature can reduce the number of wrapper methods when wrapping methods with default arguments. The section on <a href="SWIGPlus.html#SWIGPlus_default_args">default arguments</a> discusses the feature and its limitations.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|