Whole document tree

3 SWIG Basics

• Running SWIG
• Simple C functions, variables, and constants
• Pointers and complex objects
• Getting down to business
• Structures, unions, and object oriented C programming
• C++ support
• Objective-C
• Conditional compilation
• Code Insertion
• A general interface building strategy

Running SWIG

swig <options> filename

-tcl                  Generate Tcl wrappers
-tcl8                 Generate Tcl 8.0 wrappers
-perl                 Generate Perl5 wrappers
-python               Generate Python wrappers
-perl4                Generate Perl4 wrappers
-guile                Generate Guile wrappers
-dascii               ASCII documentation
-dlatex               LaTeX documentation
-dhtml                HTML documentation
-dnone                No documentation
-c++                  Enable C++ handling
-objc                 Enable Objective-C handling.
-Idir                 Set SWIG include directory
-lfile                Include a SWIG library file.
-c                    Generate raw wrapper code (omit supporting code)
-v                    Verbose mode (perhaps overly verbose)
-o outfile            Name of output file
-d docfile            Set name of documentation file (without suffix)
-module name          Set name of SWIG module
-Dsymbol              Define a symbol
-version              Show SWIG's version number
-help                 Display all options

Input format

%module mymodule 
%{
#include "myheader.h"
%}
// Now list ANSI C variable and function declarations

SWIG Output

Comments

C Preprocessor directives

• #define. Used to create constants
• #ifdef,#ifndef,#else,#endif, #if, #elif. Used for conditional compilation

All other C preprocessor directives are ignored by SWIG (including macros created using #define).

SWIG Directives

Limitations in the Parser (and various things to keep in mind)

• Functions with variable length arguments (ie. "...") are not supported.
• Complex declarations such as function pointers and arrays are problematic. You may need to remove these from the SWIG interface file or hide them with a typedef.
• C++ source code (what would appear in a .C file) is especially problematic. Running SWIG on C++ source code is highly discouraged.
• More sophisticated features of C++ such as templates and operator overloading are not supported. Please see the section on using SWIG with C++ for more details. When encountered, SWIG may issue a warning message or a syntax error if it can't figure out you are trying to do.

Many of these limitations may be eliminated in future releases. It is worth noting that many of the problems associated with complex declarations can sometimes be fixed by clever use of typedef.

If you are not sure whether SWIG can handle a particular declaration, the best thing to do is try it and see. SWIG will complain loudly if it can't figure out what's going on. When errors occur, you can either remove the offending declaration, conditionally compile it out (SWIG defines a symbol SWIG that can be used for this), or write a helper function to work around the problem.

Simple C functions, variables, and constants

%module example

extern double sin(double x);
extern int strcmp(const char *, const char *);
extern int My_variable;
#define STATUS 50
const char *VERSION="1.1";

% sin 3
5.2335956
% strcmp Dave Mike
-1
% puts $My_variable
42
% puts $STATUS
50
% puts $VERSION
1.1

Integers

int
short
long
unsigned
signed
unsigned short
unsigned long
unsigned char
signed char
bool

Scripting languages usually only support a single integer type that corresponds to either the int or long datatype in C. When converting from C, all of the above datatypes are cast into the representation used by the target scripting language. Thus, a 16 bit short in C may be converted to a 32 bit integer. When integers are converted from the scripting language back into C, the value will be cast into the appropriate type. The value will be truncated if it is too large to fit into the corresponding C datatype. This truncation is not currently checked.

The unsigned char and signed char datatypes are special cases that are treated as integers by SWIG. Normally, the char datatype is mapped as an ASCII string.

The bool datatype is cast to and from an integer value of 0 and 1.

Some care is in order for large integer values. Most scripting language use 32 bit integers so mapping a 64 bit long integer may lead to truncation errors. Similar problems may arise with 32 bit unsigned integers that may show up as negative numbers. As a rule of thumb, the int datatype and all variations of char and short datatypes are safe to use. For unsigned int and long datatypes, you should verify the correct operation of your program after wrapping it with SWIG.

Floating Point

float
double

Floating point numbers are mapped to and from the natural representation of floats in the target language. This is almost always a double except in Tcl 7.x which uses character strings. The rarely used datatype of "long double" is not supported by SWIG.

Character Strings

The char * datatype is assumed to be a NULL-terminated ASCII string. SWIG maps this into a character string in the target language. SWIG converts character strings in the target language to NULL terminated strings before passing them into C/C++. It is illegal for these strings to have embedded NULL bytes although there are ways to work around this problem.

The signed char and unsigned char datatypes are mapped into integer values. The following example illustrates the mapping of char datatypes.

%{
#include <stdio.h>
#include <ctype.h>
#include <string.h>
signed char sum(signed char a, signed char b) { return a+b;}
%}

int  strcmp(char *, char *);
char toupper(char);
signed char sum(signed char a, signed char b);

A Tcl script using these functions (and the resulting output) might be as follows.

tclsh > strcmp Mike John
1
tclsh > toupper g
G
tclsh > sum 17 -8
9

Variables

%module example

double foo;

# Tcl
set foo [3.5] 			;# Set foo to 3.5
puts $foo			;# Print the value of foo

# Python
cvar.foo = 3.5			;# Set foo to 3.5
print cvar.foo			;# Print value of foo

# Perl
$foo = 3.5;			;# Set foo to 3.5
print $foo,"\n";			;# Print value of foo

Constants

#define I_CONST       5               // An integer constant
#define F_CONST       3.14159         // A Floating point constant
#define S_CONST       "hello world"   // A string constant
#define NEWLINE       '\n'            // Character constant
#define MODE          DEBUG           // Sets MODE to DEBUG.
                                      // DEBUG is assumed to be an
                                      // int unless declared earlier
enum boolean {NO=0, YES=1};
enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
             SEP, OCT, NOV, DEC};
const double PI 3.141592654;
#define F_CONST (double) 5            // A floating pointer constant with cast
#define PI_4 PI/4
#define FLAGS 0x04 | 0x08 | 0x40

The use of constant expressions is allowed, but SWIG does not evaluate them. Rather, it passes them through to the output file and lets the C compiler perform the final evaluation (SWIG does perform a limited form of type-checking however).

For enumerations, it is critical that the original enum definition be included somewhere in the interface file (either in a header file or in the %{,%} block). SWIG only translates the enumeration into code needed to add the constants to a scripting language. It needs the original enumeration declaration to retrieve the correct enum values.

Pointers and complex objects

Simple pointers

int *
double ***
char **

can be used freely in an interface file. SWIG encodes pointers into a representation containing the actual value of the pointer and a string representing the datatype. Thus, the SWIG representation of the above pointers (in Tcl), might look like the following :

_10081012_int_p
_1008e124_double_ppp
_f8ac_char_pp

A NULL pointer is represented by the string "NULL" or the value 0 encoded with type information.

All pointers are treated as opaque objects by SWIG. A pointer may be returned by a function and passed around to other C functions as needed. For all practical purposes, the scripting language interface works in exactly the same way as you would write a C program (well, with a few limitations).

The scripting language representation of a pointer should never be manipulated directly (although nothing prevents this). SWIG does not normally map pointers into high-level objects such as associative arrays or lists (for example, it might be desirable to convert an int * into an list of integers). There are several reasons for this :

• Adding special cases would make SWIG more complicated and difficult to maintain.
• There is not enough information in a C declaration to properly map pointers into higher level constructs. For example, an int * may indeed be an array of integers, but if it contains one million elements, converting it into a Tcl, Perl, or Python list would probably be an extremely bad idea.
• By treating all pointers equally, it is easy to know what you're going to get when you create an interface (pointers are treated in a consistent manner).

As it turns out, you can remap any C datatype to behave in new ways so these rules are not set in stone. Interested readers should look at the chapter on typemaps.

Run time pointer type checking

-strict 0			No type-checking (living on the edge)
-strict 1			Generate warning messages (somewhat annoying)
-strict 2			Strict type checking (the default)

By default, SWIG allows "NULL" pointers to be passed to C/C++. This has the potential to crash code and cause other problems if you are not careful. Checks can be placed on certain values to prevent this but this requires the use of typemaps (described in later chapters).

Derived types, structs, and classes

All complex datatypes are pointers

In other words, SWIG manipulates everything else by reference. This model makes sense because most C/C++ programs make heavy use of pointers and we can use the type-checked pointer mechanism already present for handling pointers to basic datatypes.

While all of this probably sounds complicated, it's really quite simple. Suppose you have an interface file like this :

%module fileio
FILE *fopen(char *, char *);
int fclose(FILE *);
unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
void *malloc(int nbytes);
void free(void *);

# Copy a file 
def filecopy(source,target):
	f1 = fopen(source,"r")
	f2 = fopen(target,"w")
	buffer = malloc(8192)
	nbytes = fread(buffer,8192,1,f1)
	while (nbytes > 0):
		fwrite(buffer,8192,1,f2)
		nbytes = fread(buffer,8192,1,f1)
	free(buffer)

What happens when SWIG encounters an unknown datatype?

void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);

SWIG has no idea what a "Matrix" is so it will assume that you know what you are doing and map it into a pointer. This makes perfect sense because the underlying C function is using pointers in the first place. Unlike C or C++, SWIG does not actually care whether Matrix has been previously defined in the interface file or not. While this may sound strange, it makes it possible for SWIG to generate interfaces from only partial information. In many cases, you may not care what a Matrix really is as long as you can pass references to one around in the scripting language interface. The downside to this relaxed approach is that typos may go completely undetected by SWIG. You can also end up shooting yourself in the foot, but presumably you've passed your programming safety course if you've made it this far.

As a debugging tool, SWIG will report a list of used, but undefined datatypes, if you run it with the -stat option.

[beazley@guinness SWIG1.1b6]$ swig -stat matrix.i
Making wrappers for Tcl
Wrapped 1 functions
Wrapped 0 variables
Wrapped 0 constants
The following datatypes were used, but undefined.
     Matrix
[beazley@guinness SWIG1.1b6]$

Typedef

typedef unsigned int size_t;

Getting down to business

Passing complex datatypes by value

double dot_product(Vector a, Vector b);

SWIG will transform this function call into the equivalent of the following :

double wrap_dot_product(Vector *a, Vector *b) {
	return dot_product(*a,*b);
}

In the scripting language, dot_product will now take references to Vectors instead of Vectors, although you may not notice the change.

Return by value

Vector cross(Vector v1, Vector v2);

Vector *wrap_cross(Vector *v1, Vector *v2) {
	Vector *result;
	result = (Vector *) malloc(sizeof(Vector));
	*(result) = cross(*v1,*v2);
	return result;
}

or if using C++ :

Vector *wrap_cross(Vector *v1, Vector *v2) {
	Vector *result = new Vector(cross(*v1,*v2)); // Uses default copy constructor
	return result;
}

SWIG is forced to create a new object and return a reference to it. It is up to the user to delete the returned object when it is no longer in use. When used improperly, this can lead to memory leaks and other problems. Personally, I'd rather live with a potential memory leak than forbid the use of such a function. Needless to say, some care is probably in order (you need to be aware of this behavior in any case).

Linking to complex variables

Vector unit_i;

gets mapped to a pair of set/get functions like this :

Vector *unit_i_get() {
	return &unit_i;
}
Vector *unit_i_set(Vector *value) {
	unit_i = *value;
	return &unit_i;
}

Returning a reference to the variable makes it accessible like any other object of this type. When setting the value, we simply make a copy of some other Vector reference. Again some caution is in order. A global variable created in this manner will show up as a reference in the target scripting language. It would be an extremely bad idea to free or destroy such a reference. Similarly, one can run into problems when copying complex C++ objects in this manner. Fortunately, in well-written modular code, excessive use (or abuse) of global variables is rare.

Arrays

int foobar(int a[40]);
void grok(char *argv[]);
void transpose(double a[20][20]);

will be processed as if they were declared like this:

int foobar(int *a);
void grok(char **argv);
void transpose(double (*a)[20]);

Multi-dimensional arrays are transformed into a single pointer since a[][] and **a are not the same thing (even though they can be used in similar ways). Rather, a[][] is mapped to *a, where *a is the equivalent of &a[0][0]. The reader is encouraged to dust off their C book and look at the section on arrays before using them with SWIG.

Be aware that use of arrays may cause compiler warnings or errors when compiling SWIG generated modules. While every attempt has been made to eliminate these problems, handling of arrays can be somewhat problematic due to the subtle differences between an array and a pointer.

Creating read-only variables

// File : interface.i

int 	a; 			// Can read/write
%readonly
int	b,c,d			// Read only variables
%readwrite
double	x,y			// read/write

The %readonly directive enables read-only mode until it is explicitly disabled using the %readwrite directive.

Renaming declarations

// interface.i

%name(my_print) extern void print(char *);
%name(foo) extern int a_really_long_and_annoying_name;

A more powerful renaming operation can be performed with the %rename directive as follows :

%rename oldname newname;

%rename print output; // Rename all `print' functions to `output'

SWIG does not perform any checks to see if the functions it adds are already defined in the target scripting language. However, if you are careful about namespaces and your use of modules, you can usually avoid these problems.

Overriding call by reference

// interface.i
%{
#include <time.h>
%}

typedef long time_t;
time_t time(time_t *t);
struct tm *localtime(%val time_t *t);
char *asctime(struct tm *);

$t = time(0);
$tm = localtime($t); # Note passing $t by value here
print $asctime($tm);

Default/optional arguments

int plot(double x, double y, int color=WHITE);

% plot -3.4 7.5 				# Use default value
% plot -3.4 7.5 10				# set color to 10 instead

Pointers to functions

void do_operation(double (*op)(double,double), double a, double b);

should be handled as follows :

typedef double (*OP_FUNC)(double,double);
void do_operation(OP_FUNC op, double a, double b);

// File : interface.i
%typedef double (*OP_FUNC)(double,double);
double do_operation(OP_FUNC op, double a, double b);

%typedef forces SWIG to generate a typedef in the C output code for you. This would allow the interface file shown to work with the original unmodified C function declaration.

Constants containing the addresses of C functions can also be created. For example, suppose you have the following callback functions :

extern double op_add(double a, double b);
extern double op_sub(double a, double b);
extern double op_mul(double a, double b);

// interface.i
typedef double (*OP_FUNC)(double,double);
...
const OP_FUNC ADD = op_add;
const OP_FUNC SUB = op_sub;
const OP_FUNC MUL = op_mul;
...

%do_operation $ADD 3 4
7
%

Structures, unions, and object oriented C programming

struct Vector {
	double x,y,z;
}

double Vector_x_get(Vector *obj) {
	return obj->x;
}
double Vector_y_get(Vector *obj) { 
	return obj->y;
}
double Vector_z_get(Vector *obj) { 
	return obj->z;
}
double Vector_x_set(Vector *obj, double value) {
	obj->x = value;
	return value;
}
double Vector_y_set(Vector *obj, double value) {
	obj->y = value;
	return value;
}
double Vector_z_set(Vector *obj, double value) {
	obj->z = value;
	return value;
}

Typedef and structures

typedef struct {
	double x,y,z;
} Vector;

typedef struct vector_struct {
	double x,y,z;
} Vector;

Character strings and structures

%module mymodule
...
struct Foo {
	char *name;
	...
}

char *Foo_name_get(Foo *obj) {
	return Foo->name;
}

char *Foo_name_set(Foo *obj, char *c) {
	if (obj->name) free(obj->name);
	obj->name = (char *) malloc(strlen(c)+1);
	strcpy(obj->name,c);
	return obj->name;
}

This seems to work most of the time, but occasionally it's not always what you want. Typemaps can be used to change this behavior if necessary.

Array members

interface.i : Line 116. Warning. Array member will be read-only

C constructors and destructors

%module mymodule
...
struct Vector {
	Vector(); 			// Tell SWIG to create a C constructor
	~Vector();			// Tell SWIG to create a C destructor
	double x,y,z;
}

Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}

void delete_Vector(Vector *v) {
	free(v);
}

As an alternative to explicitly defining constructors and destructors, SWIG can also automatically generate them using either a command line option or a pragma. For example :

swig -make_default example.i 

%module foo
...
%pragma make_default 					// Make default constructors
... declarations ...
%pragma no_default					// Disable default constructors

Adding member functions to C structures

/* file : vector.h */
...
typedef struct {
	double x,y,z;
} Vector;

// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

%include vector.h 				// Just grab original C header file
%addmethods Vector { 				// Attach these functions to struct Vector
	Vector(double x, double y, double z) {
		Vector *v;
		v = (Vector *v) malloc(sizeof(Vector));
		v->x = x;
		v->y = y;
		v->z = z;
		return v;
	}
	~Vector() {
		free(self);
	}
	double magnitude() {
		return sqrt(self->x*self->x+self->y*self->y+self->z*self->z);
	}
	void print() {
		printf("Vector [%g, %g, %g]\n", self->x,self->y,self->z);
	}
};

>>> v = Vector(3,4,0) 					# Create a new vector
>>> print v.magnitude()					# Print magnitude
5.0
>>> v.print()					# Print it out
[ 3, 4, 0 ]
>>> del v					# Destroy it

The %addmethods directive can also be used in the definition of the Vector structure. For example:

// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

typedef struct {
	double x,y,z;
	%addmethods {
		Vector(double x, double y, double z) { ... }
		~Vector() { ... }
		...
	}
} Vector;

Finally, %addmethods can be used to access externally written functions provided they follow the naming convention used in this example :

/* File : vector.c */
/* Vector methods */
#include "vector.h"
Vector *new_Vector(double x, double y, double z) {
	Vector *v;
	v = (Vector *) malloc(sizeof(Vector));
	v->x = x;
	v->y = y;
	v->z = z;
	return v;
}
void delete_Vector(Vector *v) {
	free(v);
}

double Vector_magnitude(Vector *v) {
	return sqrt(v->x*v->x+v->y*v->y+v->z*v->z);
}

// File : vector.i
// Interface file
%module mymodule
%{
#include "vector.h"
%}

typedef struct {
	double x,y,z;
	%addmethods {
		double magnitude(); 			// This will call Vector_magnitude
		...
	}
} Vector;

Nested structures

typedef struct Object {
	int objtype;
	union {
		int 	ivalue;
		double	dvalue;
		char	*strvalue;
		void	*ptrvalue;
	} intRep;
} Object;

typedef union {
	int 		ivalue;
	double		dvalue;
	char		*strvalue;
	void		*ptrvalue;
} Object_intRep;

typedef struct Object {
	int objType;
	Object_intRep intRep;
} Object;

Object_intRep *Object_intRep_get(Object *o) {
	return (Object_intRep *) &o->intRep;
}
int Object_intRep_ivalue_get(Object_intRep *o) {
	return o->ivalue;
}
int Object_intRep_ivalue_set(Object_intRep *o, int value) {
	return (o->ivalue = value);
}
double Object_intRep_dvalue_get(Object_intRep *o) {
	return o->dvalue;
}
... etc ...

# Perl5 script for accessing nested member
$o = CreateObject(); 				# Create an object somehow
$o->{intRep}->{ivalue} = 7 				# Change value of o.intRep.ivalue

If you've got a bunch of nested structure declarations, it is certainly advisable to check them out after running SWIG. However, there is a good chance that they will work. If not, you can always remove the nested structure declaration and write your own set of accessor functions.

Other things to note about structures

It is also important to note that most language modules may choose to build a more advanced interface. You may never use the low-level interface described here, although most of SWIG's language modules use it in some way or another.

C++ support

This section describes SWIG's low-level access to C++ declarations. In many instances, this low-level interface may be hidden by shadow classes or an alternative calling mechanism (this is usually language dependent and is described in detail in later chapters).

Supported C++ features

• Simple class definitions
• Constructors and destructors
• Virtual functions
• Public inheritance (including multiple inheritance)
• Static functions
• References

The following C++ features are not currently supported :

• Operator overloading
• Function overloading (without renaming)
• Templates (anything that would be defined using the `template' keyword).
• Friends
• Nested classes
• Namespaces
• Pointers to member functions.

Since SWIG's C++ support is a "work in progress", many of these limitations may be lifted in future releases. In particular, function overloading and nested classes, may be supported in the future. Operator overloading and templates are unlikely to be supported anytime in the near future, but I'm not going to rule out the possibility in later releases.

C++ example

%module list
%{
#include "list.h"
%}

// Very simple C++ example for linked list

class List {
public:
  List();
  ~List();
  int  search(char *value);
  void insert(char *);
  void remove(char *);
  char *get(int n);
  int  length;
static void print(List *l);
};

When compiling C++ code, it is critical that SWIG be called with the `-c++' option. This changes the way a number of critical features are handled with respect to differences between C and C++. It also enables the detection of C++ keywords. Without the -c++ flag, SWIG will either issue a warning or a large number of syntax errors if it encounters any C++ code in an interface file.

Constructors and destructors

List * new_List(void) {
	return new List;
}
void delete_List(List *l) {
	delete l;
}

Member functions

int List_search(List *obj, char *value) {
	return obj->search(value);
}

Static members

Member data

int List_length_get(List *obj) {
	return obj->length;
}
int List_length_set(List *obj, int value) {
	obj->length = value;
	return value;
}

class List {
public:
...
%readonly
	int length;
%readwrite
...
};

Protection

By default, members of a class definition are assumed to be private until you explicitly give a `public:' declaration (This is the same convention used by C++).

Enums and constants

class Swig {
public:
	enum {ALE, LAGER, PORTER, STOUT};
};

Swig_ALE = Swig::ALE
Swig_LAGER = Swig::LAGER
Swig_PORTER = Swig::PORTER
Swig_STOUT = Swig::STOUT

References

class Foo {
public:
	double bar(double &a);
}

will be accessed using a function like this :

double Foo_bar(Foo *obj, double *a) {
	obj->bar(*a);
}

Inheritance

SWIG does not support private or protected inheritance (it will be parsed, but ignored).

The following example shows how SWIG handles inheritance. For clarity, the full C++ code has been omitted.

// shapes.i
%module shapes
%{
#include "shapes.h"
%}

class Shape {
public:
	virtual double area() = 0;
	virtual double perimeter() = 0;
	void    set_location(double x, double y);
};
class Circle : public Shape {
public:
	Circle(double radius);
	~Circle();
	double area();
	double perimeter();
};
class Square : public Shape {
public:
	Square(double size);
	~Square();
	double area();
	double perimeter();
}

When wrapped into Perl5, we can now perform the following operations :

beazley@slack% perl5.003
use shapes;
$circle = shapes::new_Circle(7);
$square = shapes::new_Square(10);
print shapes::Circle_area($circle),"\n";
# Notice use of base class below
print shapes::Shape_area($circle),"\n";
print shapes::Shape_area($square),"\n";
shapes::Shape_set_location($square,2,-3);
print shapes::Shape_perimeter($square),"\n";
<ctrl-d>
153.93804004599999757
153.93804004599999757
100.00000000000000000
40.00000000000000000
 

Templates

// File : list.h
#define MAXITEMS 100
template<class T> class List { 						// Entire class is ignored by SWIG
private:
    T *data;
    int nitems;
public:
    List() {
      data = new T [MAXITEMS];
      nitems = 0;
    }
    ~List() {
      delete [] data;
    };
    void append(T obj) {
      if (nitems < MAXITEMS) {
        data[nitems++] = obj;
      }
    }
    int length() {
      return nitems;
    }
    T get(int n) {
      return data[n];
    }
};

// SWIG interface involving a template
%module example
%{
#include "list.h"				// Get Template definition 
%}

// Now a function involving templates
extern void PrintData(List<double> &l);

>>> print cl
_80a2df8_List<double>_p
>>>

%inline %{
// Helper function to create a List<double>
List<double> *new_DoubleList() {
	return new List<double>;
}
%}

Specific templates can also be wrapped in a clever way using typedef. For example, the following would also work :

%module example
%{
#include "list.h"
typedef List<double> DoubleList;
%}

class DoubleList {
public:
	DoubleList();
	~DoubleList();
	void append(double);
	int length();
	double get(int n);
};

Renaming

class List {
public:
  List();
%name(ListSize) List(int maxsize);
  ~List();
  int  search(char *value); 
%name(find)    void insert(char *); 
%name(delete)  void remove(char *); 
  char *get(int n);
  int  length;
static void print(List *l);
};

The %name directive can be applied to all members including constructors, destructors, static functions, data members, and enumeration values.

The class name prefix can be changed by specifying

%name(newname) class List {
...
}

Adding new methods

%module vector
%{
#include "vector.h"
%}

class Vector {
public:
	double x,y,z;
	Vector();
	~Vector();
	... bunch of C++ methods ...
	%addmethods {
		char *__str__() {
			static char temp[256];
			sprintf(temp,"[ %g, %g, %g ]", v->x,v->y,v->z);
			return &temp[0];
		}
	}
};

This code adds a __str__ method to our class for producing a string representation of the object. In Python, such a method would allow us to print the value of an object using the print command.

>>>
>>> v = Vector();
>>> v.x = 3
>>> v.y = 4
>>> v.z = 0
>>> print(v)
[ 3.0, 4.0, 0.0 ]
>>>

Partial class definitions

As a rule of thumb, running SWIG on raw C++ header or source files is currently discouraged. Given the complexity of C++ parsing and limitations in SWIG's parser it will still take some time for SWIG's parser to evolve to a point of being able to safely handle most raw C++ files.

SWIG, C++, and the Legislation of Morality

Needless to say, handling all of the possible cases is probably impossible. SWIG is certainly not guaranteed to work with every conceivable type of C++ program (especially those that use C++ in a maximal manner). Nor is SWIG claiming to build C++ interfaces in a completely "safe" manner. The bottom line is that effective use of C++ with SWIG requires that you know what you're doing and that you have a certain level of "moral flexibility" when it comes to the issue of building a useful scripting language interface.

The future of C++ and SWIG

Objective-C

Objective-C support is built using the same approach as used for C++ parsing. Objective-C interface definitions are converted into a collection of ANSI C accessor functions. These accessor functions are then wrapped by SWIG and turned into an interface.

To enable Objective-C parsing, SWIG should be given the -objc option (this option may be used in conjunction with the -c++ option if using Objective-C++). It may also be helpful to use the -o option to give the output file the .m suffix needed by many Objective-C compilers. For example :

% swig -objc -o example_wrap.m example.i

Objective-C Example

%module list
%{
#import "list.h"
%}
%include objc.i
// Very simple list class
@interface List : Object {
     int   nitems;                  // Number of items in the list
     int   maxitems;                // Maximum number of items
     id   *items;                   // Array holding the items
}
//-------------------------  List methods --------------------------

// Create a new list
+ new;

// Destroy the list
- free;

// Copy a list
- copy;

// Append a new item to the list
- (void) append: (id) item;

// Insert an item in the list
- (void) insert: (id) item : (int) pos;

// Delete an item from the list
-  remove: (int) pos;

// Get an item from the list
- get: (int) i;

// Find an item in the list and return its index
- (int) index: obj;

// Get length of the list
- (int) len;

// Print out a list (Class method)
+ (void) print: (List *) l;

@end

Constructors and destructors

List *new_List(void) {
	return (List *) [List new];
}
void delete_List(List *l) {
	[l free];
}

If your Objective-C program uses a different naming scheme for constructors and destructors, you can tell SWIG about it using the following directive :

%pragma objc_new = "create" 					// Change constructor to `create'
%pragma objc_delete = "destroy" 					// Change destructor to `destroy'

Instance methods

void List_append(List *l, id item) {
	[l append : item];
}

Class methods

void List_print(List *l) {
	[List print : l];
}

Member data

Protection

The use of id

Inheritance

Referring to other classes

Categories

%module example
%{
#import "foo.h"
%}

// Sample use of a category in an interface
@interface Foo (CategoryName)
// Method declarations
-bar : (id) i;
@end

Implementations and Protocols

Although SWIG ignores protocols, protocol type-specifiers may be used. For example, these are legal declarations :

%module example

%interface Foo : Object <proto1, proto2> {

}
// Methods
- Bar : (id <proto1,proto2>) i;
@end

Renaming

@interface List : Object {
@public
%name(size) int length; 						// Rename length to size
}

+ new;
- free;
%name(add) -(void) append: (id) item;						// Rename append to add
@end

Adding new methods

@interface List : Object {
}
... bunch of Objective-C methods ...
%addmethods {
	- (void) output {
		... code to output a list ...
	}
}
@end

%addmethods works in exactly the same manner as it does for C and C++ (except that Objective-C syntax is allowed). Consult those sections for more details.

Other issues

Certain aspects of Objective-C are not currently supported (protocols for instance). These limitations may be lifted in future releases.

Conditional compilation

#ifdef SWIG
%module mymodule
%{
#include "header.h"
%}

%include wish.i
#endif

... normal C declarations here ...

Similarly, conditional compilation can be used to customize an interface. The following interface file can be used to build a Perl5 module that works with either static or dynamic linking :

%module mymodule
%{
#include "header.h"
%}

... Declarations ...

#ifdef STATIC
%include perlmain.i 				// Include code for static linking
#endif

double foo(
#ifdef ANSI_ARGS
double a, double b
#endif
);

Defining symbols

swig -perl5 -static -DSTATIC interface.i

%module mymodule
#define STATIC 

... etc ...

For the purposes of conditional compilation, one should not assign values to symbols. If this is done, SWIG interprets the #define as providing the definition of a scripting language constant.

The #if directive

#if defined(SYMBOL)
...
#elif !defined(OTHERSYMBOL)
...
#endif

The C preprocessor version supports any constant integral expression as an argument to #if, but SWIG does not yet contain an expression evaluator so this is not currently supported. As a result, declarations such as the following don't yet work :

#if (defined(foo) || defined(bar))
...
#endif

Predefined Symbols

SWIG				Always defined when SWIG is processing a file
SWIGTCL				Defined when using Tcl
SWIGTCL8				Defined when using Tcl8.0
SWIGPERL				Defined when using Perl
SWIGPERL4				Defined when using Perl4
SWIGPERL5				Defined when using Perl5
SWIGPYTHON				Defined when using Python
SWIGGUILE				Defined when using Guile
SWIGWIN				Defined when running SWIG under Windows
SWIGMAC				Defined when running SWIG on the Macintosh

Code Insertion

The output of SWIG

The headers portion typically contains header files, supporting code, helper functions, and forward declarations. If you look at it, you'll usually find a hideous mess since this also contains the SWIG run-time pointer type-checker and internal functions used by the wrapper functions. The "wrapper" portion of the output contains all of the wrapper functions. Finally, the initialization function is a single C function that is created to initialize your module when it is loaded.

Code blocks

%module mymodule
%{
#include "my_header.h"
%}

... Declare functions here
%{

... Include Tcl_AppInit() function here ...

%}

Code blocks are also typically used to write "helper" functions. These are functions that are used specifically for the purpose of building an interface and are generally not visible to the normal C program. For example :

%{

/* Create a new vector */
static Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}

%}

// Now wrap it 
Vector *new_Vector();

Inlined code blocks

%inline %{
/* Create a new vector */
Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}
%}

Initialization blocks

%init %{

	init_variables();
%}

This code is inserted directly into SWIG's initialization function. You can use it to perform additional initialization and operations. Since this code is inserted directly into another function, it should not declare functions or include header files. Primarily this can be used to add callouts to widgets and other packages that might also need to be initialized when your extension is loaded.

Wrapper code blocks

%wrapper %{
	... a bunch of code ...
%}

A general interface building strategy

Preparing a C program for SWIG

• Identify the functions that you want to wrap. It's probably not necessary to access every single function in a C program--thus, a little forethought can dramatically simplify the resulting scripting language interface. C header files are particularly good source for finding things to wrap.
• Create a new interface file to describe the scripting language interface to your program.
• Copy the appropriate declarations into the interface file or use SWIG's %include directive to process an entire C source/header file. Either way, this step is fairly easy.
• Make sure everything in the interface file uses ANSI C/C++syntax.
• Check to make sure there aren't any functions involving function pointers, or variable length arguments since SWIG doesn't like these very much.
• Eliminate unnecessary C preprocessor directives. SWIG will probably remove most of them, but better safe than sorry. Remember, SWIG does not run the C preprocessor.
• Make sure all necessary `typedef' declarations and type-information is available in the interface file.
• If your program has a main() function, you may need to rename it (read on).
• Run SWIG and compile.

While this may sound complicated, the process turns out to be relatively easy in practice--for example, making an interface to the entire OpenGL library only takes about 5-10 minutes.

In the process of building an interface, you are encouraged to use SWIG to find problematic declarations and specifications. SWIG will report syntax errors and other problems along with the associated file and line number.

The SWIG interface file

/* File : header.h */

#include <stdio.h>
#include <math.h>

extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

/* File : interface.i */
%module mymodule
%{
#include "header.h"
%}
extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

/* File : interface.i */
%module mymodule
%include header.h

Naturally, your mileage may vary.

Why use separate interface files?

• It is rarely necessary to access every single function in a large package. Many C functions might have little or no use in a scripted environment. Therfore, why wrap them?
• Separate interface files provide an opportunity to provide more precise rules about how an interface is to be constructed.
• Interface files can provide structure and organization. For example , you can break the interface up into sections, provide documentation, and do other things that you might not normally do with an ordinary .h file.
• SWIG can't parse certain definitions that appear in header files. Having a separate file allows you to eliminate or work around these problems.
• Interface files provide a precise definition of what the interface is. Users wanting to extend the system can go to the interface file and immediately see what is available without having to dig it out of header files.

Getting the right header files

%module graphics
%{
#include <GL/gl.h>
#include <GL/glu.h>
%}

// Put rest of declarations here
...

What to do with main()

• Get rid of main() entirely. This is the brute force approach.
• Rename main() to something else. You can do this by compiling your C program with an option like -Dmain=oldmain.
• Use conditional compilation to only include main() when not using a scripting language.

Getting rid of main() may cause potential initialization problems of a program. To handle this problem, you may consider writing a special function called program_init() that initializes your program upon startup. This function could then be called either from the scripting language as the first operation, or when the SWIG generated module is loaded.

As a general note, many C programs only use the main() function to parse command line options and to set parameters. However, by using a scripting language, you are probably trying to create a program that is more interactive. In many cases, the old main() program can be completely replaced by a Perl, Python, or Tcl script.

Working with the C preprocessor

How to cope with C++

How to avoid creating the interface from hell

• Ask yourself if you really need to access particular functions. It is usually not necessary to wrap every single function in a package. In fact, you probably only need a relatively small subset.
• SWIG does not require structure definitions to operate. If you are never going to access the members of a structure, don't wrap the structure definition.
• Eliminate unneeded members of C++ classes.
• Think about the problem at hand. If you are only using a subset of some library, there is no need to wrap the whole thing.
• Write support or helper functions to simplify common operations. Some C functions may not be easy to use in a scripting language environment. You might consider writing an alternative version and wrapping that instead.

Writing a nice interface to a package requires work. Just because you use SWIG it doesn't mean that you're going to end up with a good interface. SWIG is primarily designed to eliminate the tedious task of writing wrapper functions. It does not eliminate the need for proper planning and design when it comes to building a useful application. In short, a little forethought can go a long way.

Of course,if you're primarily interested in just slapping something together for the purpose of debugging, rapid application development, and prototyping, SWIG will gladly do it for you (in fact, I use SWIG alot for this when developing other C/C++ applications).