d70f04e660
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6499 626c5289-ae23-0410-ae9c-e8d60b6d4f22
129 lines
5.3 KiB
HTML
129 lines
5.3 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Working with Modules</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="Modules"></a>15 Working with Modules</H1>
|
|
<!-- INDEX -->
|
|
<ul>
|
|
<li><a href="#Modules_nn2">The SWIG runtime code</a>
|
|
<li><a href="#Modules_nn3">A word of caution about static libraries</a>
|
|
<li><a href="#Modules_nn4">References</a>
|
|
<li><a href="#Modules_nn5">Reducing the wrapper file size</a>
|
|
</ul>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
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>
|
|
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>
|
|
|
|
|
|
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>
|
|
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="Modules_nn3"></a>15.2 A word of caution about static libraries</H2>
|
|
|
|
|
|
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.
|
|
|
|
<H2><a name="Modules_nn4"></a>15.3 References</H2>
|
|
|
|
|
|
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.
|
|
|
|
<H2><a name="Modules_nn5"></a>15.4 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>
|
|
|
|
<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>
|
|
<b>-fvirtual</b><br>
|
|
This command line option will remove the generation of superfluous virtual method wrappers.
|
|
Consider the following inheritance hierarchy:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
struct Base {
|
|
virtual void method();
|
|
...
|
|
};
|
|
|
|
struct Derived : Base {
|
|
virtual void method();
|
|
...
|
|
};
|
|
</pre>
|
|
</blockquote>
|
|
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>
|
|
<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 it's limitations.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|