SWIG (Simplified Wrapper and Interface Generator)
To use SWIG to generate wrapper code for your ANSI C or ANSI C++ libraries, follow these
steps to install, configure, and run SWIG.
Installation Requirements
Before installing SWIG, make sure that you first install the following:
- Java 1.1 or higher
- A working C++ compiler (Successfully tested with gcc version 3.2.3 on
Red Hat Linux Enterprise WS 3)
Although SWIG is capable of generating wrapper code for 13 different target languages,
the instructions provided here are specific to generating Java wrapper code.
SWIG is known to work on Unix (most flavors), Windows, and Macintosh,
but Linux is the only platform that has been tested by NeXtMidas thus far.
Installing SWIG
- Download SWIG (swig-1.3.xx.tar.gz) from the
http://www.swig.org web site. You will
need SWIG 1.3.6 or higher for compatibility with Java. The latest
release is version 1.3.25. Note: Versions of SWIG can now be found in
many Linux distributions. To make sure you have version 1.3.6+, type the
following:
$ swig -version
If SWIG is already installed, this command will show you which version
it is. If it is a version prior to 1.3.6, you will need to upgrade.
- Unzip the downloaded compressed file:
$ gunzip swig-1.3.xx.tar.gz
- Extract the SWIG files from the resulting tar file:
$ tar -xvf swig-1.3.xx.tar
- 'cd' to the directory containing the SWIG source code, and run the
configure shell script:
$ ./configure
NOTE: The SWIG installation process attempts to install the package's
files in /usr/local/bin , /usr/local/man , etc.
If you wish to install SWIG in an area other than the default, which
requires root access, run configure with the --prefix
option. For example, SWIG installed in the user's home directory:
$ configure --prefix=$HOME
- Compile the package:
$ make
- Install the programs and any data files and documentation:
$ make install
Testing SWIG
In the SWIG directory containing the source code, there is a directory of
Examples for each of the supported target languages. Follow the
instructions below to generate wrapper code for the simple Java example
located in Examples/java/simple/ , (though there are many
other Java examples to try.)
- From the SWIG directory, 'cd' to the Example directory:
$ cd Examples/java/simple/
- Run SWIG, passing it the SWIG interface file (contains header file
includes and function declarations):
$ swig -java example.i
This creates example_wrap.c and exampleJNI.java .
- Create the object files:
$ gcc -fpic -c example.c example_wrap.c \ -I$JAVAHOME/include -I$JAVAHOME/include/linux
This creates example.o and example_wrap.o .
- Create the shared library file:
$ gcc -shared example.o example_wrap.o -o libexample.so
This creates libexample.so . Make sure the path to this shared
library file is defined in your LD_LIBRARY_PATH environment variable.
- Compile the test Java program which utilizes the C library in the example:
$ javac main.java
- Run the compiled Java program:
$ java main
You should see the following output:
The gcd of 42 and 105 is 21 Foo = 3.0 Foo = 3.1415926
If you get an UnsatisfiedLinkError, check the following:
- Make sure that you named your shared library file
libexample.so
- Make sure the string passed to the
loadLibrary
function does not include the .so extension.
- Make sure your LD_LIBRARY_PATH contains the path to the native library.
- Make sure you compile both the SWIG wrapper file and the code you
are wrapping into the native library file -- the native library
will not load if there are any unresolved symbols in the compiled
C/C++ code.
More SWIG Information
For additional configuration and installation details consult the
README and INSTALL files found in the top level
SWIG directory that is created when you extract the SWIG files. Further
information about installing SWIG on different platforms or for use with
different target languages can be found at the
http://www.swig.org web site.
|