47f612c99a
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@5411 626c5289-ae23-0410-ae9c-e8d60b6d4f22
165 lines
No EOL
6 KiB
HTML
165 lines
No EOL
6 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Working with Modules</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<a name="n1"></a><H1>14 Working with Modules</H1>
|
|
<!-- INDEX -->
|
|
<ul>
|
|
<li><a href="#n2">The SWIG runtime code</a>
|
|
<li><a href="#n3">Compiling Multiple SWIG modules</a>
|
|
<li><a href="#n4">A word of caution about static libraries</a>
|
|
<li><a href="#n5">References</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 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
|
|
scripting 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.
|
|
|
|
<a name="n2"></a><H2>14.1 The SWIG runtime code</H2>
|
|
|
|
|
|
All SWIG-generated wrapper modules include 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++.
|
|
|
|
<p>
|
|
By default, 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. If two completely different SWIG modules are loaded, this
|
|
presents no problem---each module uses its own private runtime code.
|
|
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>
|
|
To solve the problem of sharing information across modules, the
|
|
SWIG runtime functions need to be exposed in a way that allows data to
|
|
be shared between modules. The next section describes how to do that.
|
|
|
|
<a name="n3"></a><H2>14.2 Compiling Multiple SWIG modules</H2>
|
|
|
|
|
|
Suppose that you have three SWIG interface files A.i, B.i, and C.i
|
|
and suppose that these modules interact with each other. To make this work,
|
|
there are two approaches you can take:
|
|
|
|
<p>
|
|
<b>Option 1:</b> Designate one module to provide the runtime code
|
|
|
|
<p>
|
|
With this option, one of the modules is designated as providing the runtime
|
|
environment. This is done with the <tt>-runtime</tt> option like this:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
% swig -runtime -c++ -python A.i
|
|
</pre>
|
|
</blockquote>
|
|
|
|
The other modules are then compiled without runtime support. This is done by
|
|
supplying the <tt>-noruntime</tt> option like this:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
% swig -noruntime -c++ -python B.i
|
|
% swig -noruntime -c++ -python C.i
|
|
</pre>
|
|
</blockquote>
|
|
|
|
To use the modules, you compile and link everything as before, but you
|
|
need to make sure that module A is loaded before all of the other
|
|
modules are used---otherwise you will unresolved symbols.
|
|
|
|
<p>
|
|
Now, the bad news: This approach may or may not work depending on the platform you
|
|
are using, what target language you are using, and the way that shared libraries work
|
|
on the system. On many systems, the symbols contained in dynamically loaded modules
|
|
are private. Therefore, even though module A provides the runtime code, the other modules
|
|
won't be able to find it. You'll know if this is the case if you try to load the other modules
|
|
and you get errors about unresolved SWIG_* functions.
|
|
|
|
<p>
|
|
<b>Option 2: Build a runtime library</b>
|
|
|
|
<p>
|
|
The second way to work with multiple modules is to create a special runtime library module.
|
|
To do this, you first build a runtime library like this:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
% swig -runtime -python swigrun.i
|
|
% # Build a shared library --- this is different on every machine! (shown for Linux)
|
|
% gcc -fpic swigrun_wrap.c -o swigrun_wrap.o
|
|
% gcc -shared swigrun_wrap.o -o libswigrunpy.so
|
|
</pre>
|
|
</blockquote>
|
|
|
|
Now, you compile all of the normal SWIG modules using the <tt>-noruntime</tt> option:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
% swig -noruntime -c++ -python A.i
|
|
% swig -noruntime -c++ -python B.i
|
|
% swig -noruntime -c++ -python C.i
|
|
</pre>
|
|
</blockquote>
|
|
|
|
Finally, when linking the dynamically loadable modules, you need to link again the special
|
|
runtime library above. For example (Linux) :
|
|
|
|
<blockquote>
|
|
<pre>
|
|
% g++ -shared A_wrap.o -L. -lswigrunpy -o _A.so
|
|
% g++ -shared B_wrap.o -L. -lswigrunpy -o _B.so
|
|
% g++ -shared C_wrap.o -L. -lswigrunpy -o _C.so
|
|
</pre>
|
|
</blockquote>
|
|
|
|
Again, all of the details will vary depending on what compiler you use, the platform, target language,
|
|
and so forth. The key point is that the runtime needs to be contained in a shared/dynamic library and
|
|
you need to link all of the modules against that library.
|
|
|
|
<p>
|
|
When you use the modules created using this technique, the runtime code will be automatically loaded
|
|
when the modules are imported. Moreover, since all of the modules are linked against the same runtime
|
|
library, they will share that code.
|
|
|
|
<a name="n4"></a><H2>14.3 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.
|
|
|
|
<a name="n5"></a><H2>14.4 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.
|
|
|
|
<p><hr>
|
|
|
|
<address>SWIG 1.3 - Last Modified : November 22, 2003</address>
|
|
</body>
|
|
</html> |