diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html index 309bfe98a..ef90ed1f6 100644 --- a/Doc/Devel/internals.html +++ b/Doc/Devel/internals.html @@ -99,13 +99,6 @@ the Engineering Manual for more info. -Runtime -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." - - Source SWIG source code is in this subdir tree. Directories marked w/ "(*)" are used in building the swig executable. diff --git a/Doc/Manual/Advanced.html b/Doc/Manual/Advanced.html index a6804e6ad..a46cf410e 100644 --- a/Doc/Manual/Advanced.html +++ b/Doc/Manual/Advanced.html @@ -104,57 +104,25 @@ Unfortunately, this problem is inherent in the method by which SWIG makes module

15.1.3 The SWIG runtime library

-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:

-

-1. Build the SWIG run-time libraries. -The SWIG/Runtime 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 Windows documentation. -If successfully built, you will end up with a number of files that are usually installed in /usr/local/lib. -The Perl, Python, Tcl and Ruby library files are listed below:

-

-

-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)
-
-

-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#.

-

-2. Compile all SWIG modules using the -c option. For example :

-

-

-% swig -c -python a.i
-% swig -c -python b.i
-
-The -c option tells SWIG to omit runtime support. It's now up to you to provide it separately--which we will do using our libraries.

-

-3. Build SWIG modules by linking against the appropriate runtime libraries.

-

-

-% swig -c -python a.i
-% swig -c -python b.i
-% gcc -c a_wrap.c b_wrap.c -I/usr/local/include
-% ld -shared a_wrap.o b_wrap.o -lswigpy  -o a.so
+To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules.
+The Working with Modules chapter describes this in further detail and how to build the SWIG runtime library. The steps can be summarised as follows:
 
-
-or if building a new executable (static linking)

-

-

-% swig -c -tcl -ltclsh.i a.i
-% gcc a_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl8 -lm -o mytclsh
+
 
-
-

When completed you should now end up with a collection of modules like this:

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.

+ +

+ +Compatibility Note: 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. +

15.1.4 A few dynamic loading gotchas

@@ -361,6 +329,6 @@ As a rule of thumb, C++ programs require somewhat more processing than C progra

-
SWIG 1.1 - Last Modified : Mon Aug 4 10:47:13 1997
+
SWIG 1.3 - Last Modified : July 9, 2004
- \ No newline at end of file + diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index 6712b8fcf..82c50ea2c 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.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. -make runtime will now produce two libraries, libguile (with the GH interface) and libguilescm -(with the SCM interface)

The GH interface to guile is deprecated. Read more about why in the Guile manual. @@ -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. -

+At least one of your modules must be compiled with the -runtime +command line switch so that one of the modules contains the runtime code. +The remaining modules must be compiled with the +-noruntime 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 +Working with Modules chapter for further details.

16.4 Underscore Folding

@@ -808,4 +801,4 @@ directive of mod2. Maybe in the future SWIG can detect dependencie - \ No newline at end of file + diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html index c8a74f5c3..192f88a33 100644 --- a/Doc/Manual/Modules.html +++ b/Doc/Manual/Modules.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.

This chapter describes the problem of using SWIG in programs @@ -32,11 +32,14 @@ where you want to create a collection of modules.

14.1 The SWIG runtime code

-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.

By default, the runtime functions are private to each SWIG-generated @@ -87,7 +90,7 @@ supplying the -noruntime 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.

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.

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: + +

+
+%module swigrun
+
+
+ +Next, build a runtime library like this: 
@@ -113,6 +125,7 @@ To do this, you first build a runtime library like this:
+ Now, you compile all of the normal SWIG modules using the -noruntime option:
@@ -135,7 +148,7 @@ runtime library above. For example (Linux) :
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.

@@ -160,6 +173,6 @@ an outside reference. John Levine's "Linkers and Loaders" is highly recommended

-
SWIG 1.3 - Last Modified : November 22, 2003
+
SWIG 1.3 - Last Modified : July 9, 2004
- \ No newline at end of file + diff --git a/Doc/Manual/Ruby.html b/Doc/Manual/Ruby.html index 0e1731f0c..696e1ca64 100644 --- a/Doc/Manual/Ruby.html +++ b/Doc/Manual/Ruby.html @@ -2957,4 +2957,4 @@ for more details).
SWIG 1.3 - Last Modified : $Date$
- \ No newline at end of file + diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index cc9e7f0a4..4a972eb04 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -2342,11 +2342,11 @@ output of SWIG is structured first.

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).