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

1. Java 1.1 or higher
2. 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

1. 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.
2. Unzip the downloaded compressed file:

       $ gunzip swig-1.3.xx.tar.gz

3. Extract the SWIG files from the resulting tar file:

       $ tar -xvf swig-1.3.xx.tar

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

5. Compile the package:

       $ make

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

1. From the SWIG directory, 'cd' to the Example directory:

       $ cd Examples/java/simple/

2. 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`.
3. 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`.
4. 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.
5. Compile the test Java program which utilizes the C library in the example:

       $ javac main.java

6. 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:
   1. Make sure that you named your shared library file `libexample.so`
   2. Make sure the string passed to the `loadLibrary` function does not include the `.so` extension.
   3. Make sure your LD_LIBRARY_PATH contains the path to the native library.
   4. 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.