SWIG Tutorial

SWIG Tutorial

SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. SWIG is used with different types of languages including common scripting languages such as Perl, PHP, Python, Tcl and Ruby. The list of supported languages also includes non-scripting languages such as C#, Common Lisp (CLISP, Allegro CL, CFFI, UFFI), Java, Lua, Modula-3, OCAML, Octave and R. Also several interpreted and compiled Scheme implementations (Guile, MzScheme, Chicken) are supported. SWIG is most commonly used to create high-level interpreted or compiled programming environments, user interfaces, and as a tool for testing and prototyping C/C++ software. SWIG can also export its parse tree in the form of XML and Lisp s-expressions. SWIG may be freely used, distributed, and modified for commercial and non-commercial use.

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, Python, Java and C#. Specifically, let's say you have them in a file 'example.c'

     /* File : example.c */
     double My_variable = 3.0;
     
     int fact(int n) {
         if (n <= 1) return 1;
         else return n*fact(n-1);
     }
     
     int my_mod(int x, int y) {
         return (x%y);
     }

     char *get_time()
     {
         time_t ltime;
         time(<ime);
         return ctime(<ime);
     }

Interface file
Now, in order to add these files to your favorite 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 :

     /* example.i */
     %module example
     %{
     /* Put header files here or function declarations like below */
     extern double My_variable;
     extern int fact(int n);
     extern int my_mod(int x, int y);
     extern char *get_time();
     %}
     
     extern double My_variable;
     extern int fact(int n);
     extern int my_mod(int x, int y);
     extern char *get_time();

Building a Tcl module
At the UNIX prompt, type the following (shown for Linux, see the SWIG Wiki Shared Libraries page for help with other operating systems):

     unix % swig -tcl example.i
     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.