Updated documentation to reflect the -runtime and -noruntime commandline options for working with multiple modules / runtime library
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6024 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton
parent
d1f74a864f
commit
41e9a9c984
7 changed files with 52 additions and 108 deletions
|
|
@ -99,13 +99,6 @@ the <a href="engineering.html">Engineering Manual</a> for more
|
|||
info.</td>
|
||||
</tr>
|
||||
|
||||
<tr><td>Runtime</td>
|
||||
<td>This subdir contains scripts and a makefile for creating runtime
|
||||
shared-object libraries used by various languages. Runtime/make.sh
|
||||
says: "The runtime libraries are only needed if you are building
|
||||
multiple extension modules that need to share information."</td>
|
||||
</tr>
|
||||
|
||||
<tr><td>Source</td>
|
||||
<td>SWIG source code is in this subdir tree. Directories marked w/ "(*)"
|
||||
are used in building the <tt>swig</tt> executable.
|
||||
|
|
|
|||
|
|
@ -104,57 +104,25 @@ Unfortunately, this problem is inherent in the method by which SWIG makes module
|
|||
<a name="n5"></a><H3>15.1.3 The SWIG runtime library</H3>
|
||||
|
||||
|
||||
To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules. This requires the use of the SWIG runtime library which is optionally built during SWIG installation. To use the runtime libraries, follow these steps:<p>
|
||||
<p>
|
||||
1. Build the SWIG run-time libraries.
|
||||
The <tt>SWIG/Runtime</tt> directory contains a makefile for doing this for Unix users.
|
||||
Some of the runtime libraries can also be built under Windows by following the instructions in the <a href="Windows.html">Windows</a> documentation.
|
||||
If successfully built, you will end up with a number of files that are usually installed in <tt>/usr/local/lib</tt>.
|
||||
The Perl, Python, Tcl and Ruby library files are listed below:<p>
|
||||
<p>
|
||||
<blockquote><pre>
|
||||
libswigpl.a # Perl library (static)
|
||||
libswigpl.so # Perl library (shared)
|
||||
libswigpy.a # Python library (static)
|
||||
libswigpy.so # Python library (shared)
|
||||
libswigtcl8.a # Tcl 8.x library (static)
|
||||
libswigtcl8.so # Tcl 8.x library (shared)
|
||||
libswigrb.a # Ruby library (static)
|
||||
libswigrb.so # Ruby library (shared)
|
||||
</pre></blockquote>
|
||||
<p>
|
||||
Note that certain libraries may be missing due to missing packages or unsupported features (like dynamic loading) on your machine. Also some languages don't use the runtime libraries at all as they implement static type checking rather than dynamic type checking, for example, Java and C#.<p>
|
||||
<p>
|
||||
2. Compile all SWIG modules using the <tt>-c</tt> option. For example :<p>
|
||||
<p>
|
||||
<blockquote><pre>
|
||||
% <b>swig -c -python a.i</b>
|
||||
% <b>swig -c -python b.i</b>
|
||||
</pre></blockquote>
|
||||
The <tt>-c</tt> option tells SWIG to omit runtime support. It's now up to you to provide it separately--which we will do using our libraries.<p>
|
||||
<p>
|
||||
3. Build SWIG modules by linking against the appropriate runtime libraries.<p>
|
||||
<p>
|
||||
<blockquote><pre>
|
||||
% <b>swig -c -python a.i</b>
|
||||
% <b>swig -c -python b.i</b>
|
||||
% <b>gcc -c a_wrap.c b_wrap.c -I/usr/local/include</b>
|
||||
% <b>ld -shared a_wrap.o b_wrap.o -lswigpy -o a.so</b>
|
||||
To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules.
|
||||
The <a href="#Modules.html">Working with Modules</a> chapter describes this in further detail and how to build the SWIG runtime library. The steps can be summarised as follows:
|
||||
|
||||
</pre></blockquote>
|
||||
or if building a new executable (static linking)<p>
|
||||
<p>
|
||||
<blockquote><pre>
|
||||
% <b>swig -c -tcl -ltclsh.i a.i</b>
|
||||
% <b>gcc a_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl8 -lm -o mytclsh</b>
|
||||
<ul>
|
||||
<li> Build the SWIG run-time libraries. </li>
|
||||
<li> Compile all SWIG modules using the <tt>-noruntime</tt> option. </li>
|
||||
<li> Build SWIG modules by linking against the appropriate runtime libraries. </li>
|
||||
</ul>
|
||||
|
||||
</pre></blockquote>
|
||||
<p>
|
||||
When completed you should now end up with a collection of modules like this:<p>
|
||||
<center><img src="ch11.3.png"></center><p>
|
||||
<p>
|
||||
<p>
|
||||
In this configuration, the runtime library manages all datatypes and other information between modules. This management process is dynamic in nature--when new modules are loaded, they contribute information to the run-time system. In the C++ world, one could incrementally load classes as needed. As this process occurs, type information is updated and base-classes learn about derived classes as needed.<p>
|
||||
|
||||
<p>
|
||||
|
||||
<b>Compatibility Note:</b> In SWIG-1.3.19 and earlier releases, SWIG built the runtime libraries by default and attempted to install them with the SWIG installation. This had numerous limitations, not least, the version of the target language was tied to what was detected at installation time and would not necessarily be the version the user required.
|
||||
|
||||
<a name="n6"></a><H3>15.1.4 A few dynamic loading gotchas</H3>
|
||||
|
||||
|
||||
|
|
@ -361,6 +329,6 @@ As a rule of thumb, C++ programs require somewhat more processing than C progra
|
|||
|
||||
<p><hr>
|
||||
|
||||
<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:13 1997</address>
|
||||
<address>SWIG 1.3 - Last Modified : July 9, 2004</address>
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -67,8 +67,6 @@ The "-gh" wrapper generation can be used for older versions of guile. Thus even
|
|||
the guile GH wrapper code generation will be depreciated (as guile 1.6 and above become more common) and the
|
||||
SCM interface will become the default. The SCM and GH interface differ greatly in how they store
|
||||
pointers and have completely different run-time code. See below for more info.
|
||||
<code>make runtime</code> will now produce two libraries, libguile (with the GH interface) and libguilescm
|
||||
(with the SCM interface)</p>
|
||||
|
||||
<p>The GH interface to guile is deprecated. Read more about why in the
|
||||
<a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
|
||||
|
|
@ -295,21 +293,16 @@ experimental; the (hobbit4d link) conventions are not well understood.
|
|||
|
||||
|
||||
If you want to use multiple SWIG modules, they have to share some
|
||||
run-time data for the typing system. You have two options:
|
||||
run-time data for the typing system.
|
||||
|
||||
<ul>
|
||||
<li>Either generate all but one wrapper module with
|
||||
the <code>-c</code> command-line argument. Compile all wrapper files
|
||||
with the C compiler switch <code>-DSWIG_GLOBAL</code>.
|
||||
|
||||
<li>Or generate all wrapper modules with the <code>-c</code>
|
||||
command-line argument and compile all wrapper files with the C
|
||||
compiler switch <code>-DSWIG_GLOBAL</code>. Then link against the
|
||||
runtime library <code>libswigguile</code> or <code>libswigguilescm</code>, which is built by
|
||||
<code>make runtime</code>. The needed linker flags are reported by
|
||||
SWIG if you invoke it with the <code>-guile -ldflags</code>
|
||||
command-line arguments.
|
||||
</ul>
|
||||
At least one of your modules must be compiled with the <code>-runtime</code>
|
||||
command line switch so that one of the modules contains the runtime code.
|
||||
The remaining modules must be compiled with the
|
||||
<code>-noruntime</code> commandline switch and linked with the module
|
||||
with the runtime code. You could create an empty swig module and use that
|
||||
to generate the runtime code instead of placing the runtime code into a
|
||||
module with code that is being wrapped. See the
|
||||
<a href="#Modules.html">Working with Modules</a> chapter for further details.
|
||||
|
||||
<a name="n11"></a><H2>16.4 Underscore Folding</H2>
|
||||
|
||||
|
|
@ -808,4 +801,4 @@ directive of <code>mod2</code>. Maybe in the future SWIG can detect dependencie
|
|||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -19,11 +19,11 @@
|
|||
|
||||
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
|
||||
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
|
||||
scripting interface when it is broken up into smaller pieces.
|
||||
target language interface when it is broken up into smaller pieces.
|
||||
|
||||
<p>
|
||||
This chapter describes the problem of using SWIG in programs
|
||||
|
|
@ -32,11 +32,14 @@ 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
|
||||
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++.
|
||||
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>
|
||||
By default, the runtime functions are private to each SWIG-generated
|
||||
|
|
@ -87,7 +90,7 @@ supplying the <tt>-noruntime</tt> option like this:
|
|||
|
||||
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.
|
||||
modules are used---otherwise you will get unresolved symbols.
|
||||
|
||||
<p>
|
||||
Now, the bad news: This approach may or may not work depending on the platform you
|
||||
|
|
@ -102,7 +105,16 @@ and you get errors about unresolved SWIG_* functions.
|
|||
|
||||
<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:
|
||||
To do this, you first need to create an empty SWIG interface file, say swigrun.i, containing
|
||||
just the %module directive, for example:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
%module swigrun
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
Next, build a runtime library like this:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -113,6 +125,7 @@ To do this, you first build a runtime library like this:
|
|||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
||||
Now, you compile all of the normal SWIG modules using the <tt>-noruntime</tt> option:
|
||||
|
||||
<blockquote>
|
||||
|
|
@ -135,7 +148,7 @@ runtime library above. For example (Linux) :
|
|||
</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
|
||||
and so forth. The key point is that the runtime needs to be contained in a shared/dynamic library (DLL) and
|
||||
you need to link all of the modules against that library.
|
||||
|
||||
<p>
|
||||
|
|
@ -160,6 +173,6 @@ an outside reference. John Levine's "Linkers and Loaders" is highly recommended
|
|||
|
||||
<p><hr>
|
||||
|
||||
<address>SWIG 1.3 - Last Modified : November 22, 2003</address>
|
||||
<address>SWIG 1.3 - Last Modified : July 9, 2004</address>
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -2957,4 +2957,4 @@ for more details).
|
|||
|
||||
<address>SWIG 1.3 - Last Modified : $Date$</address>
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -2342,11 +2342,11 @@ output of SWIG is structured first.<p>
|
|||
|
||||
|
||||
When SWIG creates its output file, it is broken up into four sections
|
||||
corresponding to runtime libraries, headers, wrapper functions, and module
|
||||
corresponding to runtime code, headers, wrapper functions, and module
|
||||
initialization code (in that order).
|
||||
|
||||
<ul>
|
||||
<li><b>Runtime libraries</b>. <br>
|
||||
<li><b>Runtime code</b>. <br>
|
||||
This code is internal to SWIG and is used to include
|
||||
type-checking and other support functions that are used by the rest of the module.
|
||||
|
||||
|
|
@ -2657,4 +2657,4 @@ The bottom line: don't do this.
|
|||
|
||||
<address>SWIG 1.3 - Last Modified : August 7, 2003</address>
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -11,7 +11,6 @@
|
|||
<li><a href="#n2">Installation on Windows</a>
|
||||
<ul>
|
||||
<li><a href="#n3">Windows Executable</a>
|
||||
<li><a href="#n4">Runtime Libraries</a>
|
||||
</ul>
|
||||
<li><a href="#n5">SWIG Windows Examples</a>
|
||||
<ul>
|
||||
|
|
@ -42,7 +41,7 @@
|
|||
|
||||
|
||||
This chapter describes SWIG usage on Microsoft Windows.
|
||||
Installing SWIG and running the examples is covered as well as building the SWIG executable and runtime libraries.
|
||||
Installing SWIG and running the examples is covered as well as building the SWIG executable.
|
||||
Usage within the Unix like environments MinGW and Cygwin is also detailed.
|
||||
|
||||
|
||||
|
|
@ -62,27 +61,6 @@ The swigwin distribution contains the SWIG Windows executable, swig.exe, which w
|
|||
If you want to build your own swig.exe have a look at <a href="#swig_exe">Building swig.exe on Windows</a>.
|
||||
<p>
|
||||
|
||||
<a name="n4"></a><H3>2.1.2 Runtime Libraries</H3>
|
||||
|
||||
|
||||
The vast majority of users do not use the SWIG runtime libraries so feel free to ignore this section.
|
||||
The <a href="Advanced.html">Advanced Topics</a> chapter has further details on the runtime libraries.
|
||||
<p>
|
||||
|
||||
The runtime libraries which can be built have a Visual C++ project file (.dsp) file in the top level Runtime directory.
|
||||
Before starting Visual C++, set the environment variables for your target language as described in the <a href="#examples">SWIG Windows Examples</a> section.
|
||||
Next start Visual C++ and load the project file for your target language.
|
||||
Visual Studio will create a workspace file for you.
|
||||
Ensure the Release build is selected then do a Rebuild All from the Build menu; the required environment variables are displayed with their current values.
|
||||
If all goes well the runtime library dll will appear in the Runtime directory.
|
||||
<p>
|
||||
|
||||
Whenever using the runtime library, link against the <tt>.lib</tt> file which also is generated into this directory.
|
||||
Ensure the dll is in the Windows path when executing your program requiring the dll.
|
||||
<p>
|
||||
|
||||
Note that the runtime libraries can also be built on Cygwin and is automatically done as part of the general build process on Cygwin.
|
||||
|
||||
|
||||
<a name="examples"></a>
|
||||
<a name="n5"></a><H2>2.2 SWIG Windows Examples</H2>
|
||||
|
|
@ -210,7 +188,6 @@ Normally this is not needed, so most people will want to ignore this section.
|
|||
Note that SWIG can also be built using Cygwin.
|
||||
However, the SWIG will then require the Cygwin DLL when executing.
|
||||
Follow the Unix instructions in the README file in the SWIG root directory.
|
||||
The runtime libraries are also built as part of this build process.
|
||||
Note that the Cygwin environment will also allow one to regenerate the autotool generated files which are supplied with the release distribution.
|
||||
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
|
||||
<p>
|
||||
|
|
@ -234,4 +211,4 @@ Follow the Unix instructions in the README file in the SWIG root directory to bu
|
|||
<p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
</html>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue