diff --git a/SWIG/Doc/Manual/Advanced.html b/SWIG/Doc/Manual/Advanced.html index 462dda4e7..588ca43d1 100644 --- a/SWIG/Doc/Manual/Advanced.html +++ b/SWIG/Doc/Manual/Advanced.html @@ -36,10 +36,14 @@ SWIG can be used to create packages consisting of many different modules. However, there are some technical aspects of doing this and techniques for managing the problem.

+This chapter doesn't apply to those languages that use static type checking, rather than runtime type checking, such as Java and C#.

13.1.1 Runtime support (and potential problems)

-All SWIG generated modules rely upon a small collection of functions that are used during run-time. These functions are primarily used for pointer type-checking, exception handling, and so on. When you run SWIG, these functions are included in the wrapper file (and declared as static). If you create a system consisting of many modules, each one will have an identical copy of these runtime libraries :

+Most SWIG generated modules rely upon a small collection of functions that are used during run-time. +These functions are primarily used for pointer type-checking, exception handling, and so on. +When you run SWIG, these functions are included in the wrapper file (and declared as static). +If you create a system consisting of many modules, each one will have an identical copy of these runtime libraries :

This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next).

@@ -102,7 +106,11 @@ Unfortunately, this problem is inherent in the method by which SWIG makes module 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. If successfully built, you will end up with 8 files that are usually installed in /usr/local/lib.

+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)
@@ -115,7 +123,7 @@ 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.

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

@@ -138,7 +146,7 @@ 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 -lswigtcl -lm -o mytclsh
+% gcc a_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl8 -lm -o mytclsh

@@ -169,7 +177,7 @@ Now, run SWIG and compile as follows:

 % swig -c -tcl mytclsh.i
-% gcc mytclsh_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl -ldl -lm \
+% gcc mytclsh_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl8 -ldl -lm \
       -o tclsh
This produces a new executable "tclsh" that contains a copy of the SWIG runtime library. The weird __embedfunc() function is needed to force the functions in the runtime library to be included in the final executable.

@@ -181,28 +189,36 @@ To make new dynamically loadable SWIG modules, simply compile as follows :

% gcc -c example_wrap.c -I/usr/local/include % ld -shared example_wrap.o -o example.so -Linking against the swigtcl library is no longer necessary as all of the functions are now included in the tclsh executable and will be resolved when your module is loaded.

+Linking against the swigtcl8 library is no longer necessary as all of the functions are now included in the tclsh executable and will be resolved when your module is loaded. +However, some operating systems, like Windows, will still require linking with the libraries so that there are no unresolved symbols.

2. Using shared library versions of the runtime library

-If supported on your machine, the runtime libraries will be built as shared libraries (indicated by a .so, .sl, or .dll suffix). To compile using the runtime libraries, you link process should look something like this:

+If supported on your machine, the runtime libraries will be built as shared libraries (for example a .so, .sl, or .dll suffix). To compile using the runtime libraries, your link process should look something like this:

+ 

-% ld -shared swigtcl_wrap.o -o libswigtcl.so             # Irix
-% gcc -shared swigtcl_wrap.o -o libswigtcl.so            # Linux
-% ld -G swigtcl_wrap.o -o libswigtcl.so                  # Solaris
+% ld -shared example_wrap.o -o libexample.so             # Irix
+% gcc -shared example_wrap.o -o libexample.so            # Linux
+% ld -G example_wrap.o -o libexample.so                  # Solaris
+> cl /LD example_wrap.obj /o example.dll swigtcl8.lib tcl83.lib /link /LIBPATH:c:\SWIG\Runtime /LIBPATH:c:\Tcl\lib # Windows VC++
-In order for the libswigtcl.so library to work, it needs to be placed in a location where the dynamic loader can find it. Typically this is a system library directory (ie. /usr/local/lib or /usr/lib).

+ +In order for the libexample.so library to work, it needs to be placed in a location where the dynamic loader can find it. +Typically this is a system library directory (eg. /usr/local/lib or /usr/lib).

When running with the shared libary version, you may get error messages such as the following:

-

Unable to locate libswigtcl.so
-This indicates that the loader was unable to find the shared libary at run-time. To find shared libaries, the loader looks through a collection of predetermined paths. If the libswigtcl.so file is not in any of these directories, it results in an error. On most machines, you can change the loader search path by changing the Unix environment variable LD_LIBRARY_PATH, e.g.

+

Unable to locate libexample.so
+This indicates that the loader was unable to find the shared libary at run-time. +To find shared libaries, the loader looks through a collection of predetermined paths. +If the shared library file is not in any of these directories, it results in an error. +On most machines, you can change the loader search path by changing the path (Windows) or environment variable LD_LIBRARY_PATH (Unix), e.g.

% setenv LD_LIBRARY_PATH .:/home/beazley/packages/lib
A somewhat better approach is to link your module with the proper path encoded. This is typically done using the `-rpath' or `-R' option to your linker (see the man page). For example:

% ld -shared example_wrap.o example.o -rpath /home/beazley/packages/lib \
-       -L/home/beazley/packages/lib -lswigtcl.so -o example.so
+       -L/home/beazley/packages/lib -lswigtcl8.so -o example.so
The -rpath option encodes the location of shared libraries into your modules and gets around having to set the LD_LIBRARY_PATH variable.