SWIG Tutorial

So you want to get going in a hurry? To illustrate the use of SWIG, suppose you have some C functions you want added to Tcl, Perl, and Python. Specifically, let's say you have them in a file 'example.c'

Interface file

Now, in order to add these files to your favorite scripting language, you need to write an "interface file" which is the input to SWIG. An interface file for these C functions might look like this :

Building a Tcl module

At the UNIX prompt, type the following (shown for Linux): 

unix % swig -tcl example.i
Making wrappers for Tcl
unix % gcc -fpic -c example.c example_wrap.c \
       -I/usr/local/include 
unix % gcc -shared example.o example_wrap.o -o example.so
unix % tclsh
% load ./example.so example
% puts $My_variable
3.0
% fact 5
120
% my_mod 7 3
1
% get_time
Sun Feb 11 23:01:07 1996

%
The swig command produces a file example_wrap.c that should be compiled and linked with the rest of the program. In this case, we have built a dynamically loadable extension that can be loaded into the Tcl interpreter using the 'load' command.

If your machine does not support dynamic loading, it is also easy to build a new version of the tclsh interpreter as follows : 


unix % swig -tcl -ltclsh.i example.i
unix % gcc example.c example_wrap.c -I/usr/local/include \
       -L/usr/local/lib -ltcl -lsocket -ldl -lm -o my_tclsh
unix % my_tclsh
% puts $My_variable
3.0
% fact 5
120
%
In this case, the new version of tclsh is functionally identical to the original, but has new functions added to it.

Building a Python module

Turning C code into a Python module is also easy. Simply do the following (shown for Irix): 

unix % swig -python example.i
Making wrappers for Python
unix % gcc -c example.c example_wrap.c \
       -I/usr/local/include/python1.4 \
       -I/usr/local/lib/python1.4/config
unix % ld -shared example.o example_wrap.o -o examplemodule.so
We can now use the Python module as follows : 
>>> import example
>>> example.fact(5)
120
>>> example.my_mod(7,3)
1
>>> example.get_time()
'Sun Feb 11 23:01:07 1996'
>>>

Building a Perl module

Finally, you can build a Perl5 module as follows (shown for Solaris): 
unix % swig -perl5 example.i
Making wrappers for Perl5
unix % gcc -c example.c example_wrap.c \
       -I/usr/lib/perl/solaris/5.003/CORE 
unix % ld -G example.o example_wrap.o -o example.so
unix % perl
use example;
print $example::My_variable,"\n";
print example::fact(5),"\n";
print example.get_time(),"\n";
<ctrl-d>
3.0
120
Sun Feb 11 23:01:07 1996
unix %

SWIG for the truly lazy

As it turns out, it is not always necessary to write a special interface file. If your C code is relatively clean, you can just run SWIG directly on the source like this : 
unix % swig -tcl -module example example.c
unix % gcc -c example.c example_wrap.c -I/usr/local/include
unix % ld -shared example.o example_wrap.o -o example.so

Adding Documentation

Documentation can now be added using C/C++ comments. For example : We can now run SWIG using :
This will produce a documentation file example_wrap.html .

The documentation system produces documentation using the syntax of the target language. Thus, if you used Perl5 instead of Tcl, the documentation file might look like this .

Documentation can also be produced in ASCII and LaTeX formats. The C/C++ comments containing documentation can span multiple lines and can include embedded LaTeX or HTML if desired.

Running SWIG under Windows NT

SWIG also works perfectly well under Windows NT/95 systems. SWIG is typically invoked from the command prompt and can be used with NMAKE. Modules are typically compiled in the form of a DLL that can be dynamically loaded into Tcl,Python, or Perl. With a little work, SWIG can also be used as a custom build option within MS Developer Studio.

That's it (well, mostly)

That's about everything you need to know. Here's the short checklist :