c3338b1a16
- Update all languages to new type system - Add DohSortList function - Fix mzscheme Examples/Makefile git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6930 626c5289-ae23-0410-ae9c-e8d60b6d4f22
175 lines
7.8 KiB
HTML
175 lines
7.8 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="#external_run_time">External access to runtime system</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>
|
|
<!-- 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="external_run_time"></a>15.2 External access to the run-time system</a></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 are three headers you need
|
|
to include. They are located in the Lib directory in the SWIG source, or wherever the
|
|
SWIG Library was installed. You can see the current library path by running
|
|
<tt>swig -swiglib</tt>.</p>
|
|
|
|
<blockquote><pre>
|
|
#include <swigrun.swg>
|
|
#include <python/pyrun.swg> /* Or other header, see below */
|
|
#include <runtime.swg>
|
|
</pre></blockquote>
|
|
|
|
<p>After including these three headers, your code should 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 these headers 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 wrapping language. It is also
|
|
possible to copy these three header files into your own package for distribution along with
|
|
the generated wrapper files, so that you can distribute a package that can be compiled
|
|
without SWIG installed (this works because the header files are self contained, and do not
|
|
need to link with anything).</p>
|
|
|
|
<p>The headers that should be included in place of the #include <python/pyrun.swg>
|
|
for the different language modules are:</p>
|
|
<ul>
|
|
<li>Chicken - <chicken/chickenrun.swg></li>
|
|
<li>Guile (scm) - <guile/guile_scm_run.swg></li>
|
|
<li>Guile (gh) - This does not work with the -gh API, use the -scm API</li>
|
|
<li>MzScheme - <mzscheme/mzrun.swg></li>
|
|
<li>Ocaml - <ocaml/ocaml.swg></li>
|
|
<li>Python - <python/pyrun.swg></li>
|
|
<li>Perl5 - <perl5/perlrun.swg></li>
|
|
<li>Ruby - <ruby/rubydef.swg></li>
|
|
<li>Tcl - <tcl/swigtcl8.swg></li>
|
|
</ul>
|
|
|
|
<H2><a name="Modules_nn4"></a>15.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.
|
|
|
|
<H2><a name="Modules_nn5"></a>15.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.
|
|
|
|
<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>
|
|
|
|
<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>
|