Perl Extension Building with SWIG

David M. Beazley
Dept. of Computer Science
University of Chicago
Chicago, IL 60637

David Fletcher
Fusion MicroMedia, Corp.
Longmont, CO 80501

Dominique Dumont
Hewlett Packard
Lab TID
5 Ave Raymond Chanas
38053 Grenoble cedex
France

[ PDF ]

Abstract

1 Introduction

The integration of Perl and code written in compiled languages has a number of practical benefits. First, it allows existing C/C++ applications to be incorporated into a high-level interpreted environment. This environment provides greater flexibility and often simplifies development since debugging and testing can be performed using Perl scripts. Second, Perl can serve as a powerful user interface. In other words, rather than writing a user interface from scratch, it is possible to use a Perl interpreter instead. This also allows other for other possibilities such as graphical user interface development with Perl/Tk. Finally, Perl provides developers with a mechanism for assembling and controlling software components. Rather than creating a huge monolithic package, C/C++ programs can be packaged as collections of Perl extension modules. As a result, programs become more modular and easier to maintain. Furthermore, it is even possible to combine entirely different programs together within a shared Perl interpreter.

This paper provides an introduction and overview of SWIG, a tool designed to integrate C code with a variety of scripting languages including Perl, Python, and Tcl. Currently, SWIG can construct Perl extension modules on Unix and Windows-NT systems. It also supports the ActiveState Perl for Windows and Perl4. SWIG has been freely available since February, 1996 and has been previously described in Advanced Perl Programming, The Perl Journal, and Dr. Dobb's Journal[1,2,3]. In addition, SWIG is packaged with a 300 page user manual describing its use [4]. The goal of this paper is not to repeat all of this information, but to provide an overview of SWIG, demonstrate the use of some of its more advanced features, and describe some of the ways that it is currently being used. The authors include the developer of SWIG and two of SWIG's foremost Perl experts who have made substantial contributions to SWIG's development.

2 Perl Extension Building

int fact(int n);

/* file : example.xs */
extern int fact(int n);
MODULE = Example     PACKAGE = Example
int
fact(n)
     int    n

#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
extern int fact(int n);

XS(XS_Example_fact)
{
    dXSARGS;
    if (items != 1)
        croak("Usage: Example::fact(n)");
    {
        int     n = (int)SvIV(ST(0));
        int     RETVAL;
        RETVAL = fact(n);
        ST(0) = sv_newmortal();
        sv_setiv(ST(0), (IV)RETVAL);
    }
    XSRETURN(1);
}

XS(boot_Example)
{
    dXSARGS;
    char* file = __FILE__;
    XS_VERSION_BOOTCHECK ;
    newXS("Example::fact", 
           XS_Example_fact, file);
    ST(0) = &sv_yes;
    XSRETURN(1);
}

# file : Makefile.PL
use ExtUtils::MakeMaker;
WriteMakefile(
   'NAME' => 'Example',
   'OBJECT' => 'example.o fact.o'
);

unix > perl Makefile.PL
unix > make
unix > make install

# file : Example.pm
package Example;
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
bootstrap Example;
1;

3 SWIG Overview

3.1 A Small Taste

Since gd is a C library, images are normally created by writing C code such as follows:

#include "gd.h"
int main() {
  gdImagePtr  im;
  FILE       *out;
  int         blk,wht;

  /* Create an image */
  im=gdImageCreate(200,200);
  
  /* Allocate some colors */
  blk=gdImageColorAllocate(im,0,0,0);
  wht=gdImageColorAllocate(im,255,255,255);

  /* Draw a line */
  gdImageLine(im,20,50,180,140,wht);

  /* Output the image */
  out=fopen("test.gif","wb");
  gdImageGif(im,out);
  fclose(out);

  /* Clean up */
  gdImageDestroy(im);
}

// File : gd.i
%module gd
%{
#include "gd.h"
%}

typedef gdImage *gdImagePtr;

gdImagePtr gdImageCreate(int sx, int sy);
void       gdImageDestroy(gdImagePtr im);
void       gdImageLine(gdImagePtr im, 
                      int x1, int y1,
                      int x2, int y2,
                      int color);
int   gdImageColorAllocate(gdImagePtr im,
                      int r, int g, int b);
void  gdImageGif(gdImagePtr im, FILE *out);

// File I/O functions (explained shortly)
FILE *fopen(char *name, char *mode);
void  fclose(FILE *);

To run SWIG, the following command is executed:

unix > swig -perl5 gd.i
Generating wrappers for Perl 5

To build the module, the wrapper file is compiled and linked into a shared library. This process varies on every machine (consult the man pages), but the following steps are performed on Linux:

unix > gcc -fpic -c gd_wrap.c \
   -Dbool=char \
   -I/usr/lib/perl5/i586-linux/5.004/CORE
unix > gcc -shared gd_wrap.o -lgd -o gd.so

#!/usr/bin/perl
use gd;

# Create an image
$im = gd::gdImageCreate(200,200);

# Allocate some colors
$blk=gd::gdImageColorAllocate($im,0,0,0);
$wht=gd::gdImageColorAllocate($im,255,
                              255,255);

# Draw a line 
gd::gdImageLine($im,20,50,180,140,$wht);

# Output the image
$out=gd::fopen("test.gif","wb");
gd::gdImageGif($im,$out);
gd::fclose($out);

# Clean up 
gd::gdImageDestroy($im);

3.2 Input Files

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

// Grab the declarations from gd.h
%include "gd.h"

// Some file I/O functions
FILE *fopen(char *name, char *mode);
void  fclose(FILE *);

SWIG also includes a C preprocessor that can be used for macro expansion and conditional compilation. If a new application is being written with SWIG in mind, header files can be written as follows:

#ifdef SWIG
%module gd
%{
#include "gd.h"
%}
#endif

/* C declarations */
...

Finally, for the truly lazy, SWIG can sometimes be run directly on C header and source files. For example,

% swig -perl5 -module gd gd.h
% swig -perl5 -module example example.c

3.3 Data Model

3.3.1 Pointers

gdImagePtr=SCALAR(0x80b9914)

% perl
use gd;
$f = gd::fopen("test.gif","w");
gd::gdImageLine($f,20,50,180,140,0);
Type error in argument 1 of gdImageLine. 
Expected gdImagePtr. at - line 3.

When pointers are manipulated in Perl, they are opaque values. That is, pointers can be created and passed around to other C functions, but they can not be dereferenced directly. Thus, in the example, it is difficult (or impractical) for a user to directly manipulate the internal representation of an image from the Perl interpreter. Furthermore, SWIG, by default, handles all pointers in a uniform manner. Thus, datatypes such as FILE * are represented as blessed references even though such types may appear remarkably similar to other Perl datatypes such as file handles.

3.3.2 Arrays

void foo(double a[4][4]);

3.3.3 Structures and Objects

double dot_product(Vector a, Vector b);
Vector cross_product(Vector a, Vector b);

double
wrap_dot_product(Vector *a, Vector *b) {
  return dot_product(*a,*b);
}
Vector *
wrap_cross_product(Vector *a, Vector *b) {
  Vector *r;
  r = (Vector *) malloc(sizeof(Vector));
  *r = cross_product(*a,*b);
  return r;
}

The downside to this approach is that objects are opaque in Perl. This prevents users from examining their contents directly. In addition, SWIG wrappers occasionally need to perform implicit memory allocations as shown above. It is up the user to free the resources used by such functions (or learn to live with a memory leak). Of course, this naturally brings us to the next topic.

3.3.4 Memory Management

From a user standpoint, SWIG generated C/C++ extensions follow the same memory management rules as the underlying application. Thus, if a program relies on malloc and free to allocate and deallocate objects, these will also be used from the Perl interpreter. Likewise, a C++ extension typically requires explicit invocation of constructors and destructors. Furthermore, for functions that implicitly allocate memory as in the previous section, it is up to the user to explicitly destroy the result using free or a C++ destructor. While such a scheme may seem problematic, it is no less problematic than memory management in C (which may or may not be a good thing depending on your point of view). Even if it were possible to have Perl automatically manage C/C++ objects, this would be an inherently dangerous affair--especially since Perl has no way to know how an underlying C application really operates. Furthermore, it would be a fatal error for Perl to deallocate objects that were still in use. Therefore, SWIG leaves memory management largely up the user.

3.3.5 Pointers, Arrays, and Perl

The difference between Perl and C datatypes often arises with C functions such as the following:

/* Plot some points */
void
plotpts(gdImagePtr im, int x[], int y[],
        int npts,  int c)
{
   for (int i = 0; i < npts; i++) {
      gdImageSetPixel(im,x[i],y[i],c);
   }
}

@a = (10,20,30,40);
@b = (50,70,60,200);
gd::plotpts($im,\@a,\@b,4,1); # Error!

It should also be noted that SWIG provides a variety of customization options that can be used to change its behavior. In fact, one can even make SWIG map Perl arrays into C arrays if desired. Therefore, most restrictions can be eliminated with a little extra work. Some of these customization techniques are described shortly.

3.4 Helper Functions

// Add some helper functions for C arrays
%inline %{
int *int_array(int size) {
   return (int *) malloc(sizeof(int)*size);
}
void int_destroy(int *a) {
   free(a);
}
void int_set(int *a, int i, int val) {
   a[i] = val;
}
int int_get(int *a, int i) {
   return a[i];
}
%}

# Convert a Perl array into a C int array
sub create_array {
 $len = scalar(@_);
 $ia = gd::int_array($len);
 for ($i = 0; $i < $len; $i++) {
    val = shift;
    gd::int_set($ia,$i,$val);
 }
 return $ia;
}
   
@a = (10,20,30,40);
@b = (50,70,60,200);
$ia = create_array(@a);  # Create C arrays
$ib = create_array(@b);
gd::plotpts($im,$ia,$ib,4,1);
...
gd::int_destroy($ia);
gd::int_destroy($ib);

3.5 Classes and Structures

/* Extract data from an object */
double Point_x_get(Point *p) {
    return p->x;
}
/* Invoke a C++ member function */
int Foo_bar(Foo *f) {
    return f->bar();
}

While it is possible to write accessor functions manually, SWIG automatically creates them when it is given structure and class definitions. For example, in the gd library, the following structure is used to contain image information:

typedef struct gdImageStruct {
        unsigned char ** pixels;
        int sx;
        int sy;
        int colorsTotal;
...
} gdImage;

#!/usr/bin/perl
use gd;
$im = gd::gdImageCreate(400,300);
# Print out the image width
print gd::gdImage_sx_get($im), "\n";

class List {
public:
   List();
  ~List();
   void insert(Object *);
   Object *get(int i);
   int  length();
   ...
};

List *new_List() {
   return new List;
}
void delete_List(List *l) {
   delete l;
}
void List_insert(List *l, Object *o) {
   l->insert(o);
} 
...

3.6 Shadow Classes and Perl Objects

package List;
@ISA = qw( example );
sub new {
    my $self = shift;
    my @args = @_;
    $self = new_List(@args);
    return undef if (!defined($self));
    bless $self, "List";
    my %retval;
    tie %retval, "List", $self;
    return bless \%retval,"List";
}
sub DESTROY {
    delete_List(@_);
}
sub insert {
    return $result = List_insert(@_);
}
...

$l = new List;
$l->insert($o);
...
$l->DESTROY();

$im = gd::gdImageCreate(400,400);
$width = $im->{sx};
$height = $im->{sy};
...

3.7 Class Extension

typedef struct {
    int x,y;
} gdPoint;

/* Add some methods to points */
%addmethods gdPoint {
/* Create a point or an array of points */
gdPoint(int npts = 1) {
  return (gdPoint *) 
      malloc(sizeof(gdPoint)*npts);
}
/* Destroy a point */
~gdPoint() {
  free(self);
}
/* Array indexing */
gdPoint *get(int i) {
  return self+i;
}
/* A debugging function */
void output() {
  printf("(%d,%d)\n",self->x,self->y);
}
};

# Create a point
$pt = new gdPoint;
$pt->{x} = 20;
$pt->{y} = 50;
$pt->output();

# Create an array of points
$pts = new gdPoint(10);
for ($i = 0; $i < 10; $i++) {
   $p = $pts->get($i);
   $p->{x} = $i;
   $p->{y} = 10*$i;
}

# Pass the points to a function
gd::gdImagePolygon($im,$pts,10,1);
...

%addmethods gdImage {
gdImage(int w, int h) {
  return gdImageCreate(w,h);
}
~gdImage() {
  gdImageDestroy(self);
}
int
colorAllocate(int r, int g, int b) {
  return gdImageColorAllocate(self,r,g,b);
}
void
line(int x1,int y1,int x2,int y2,int c) {
  gdImageLine(self,x1,y1,x2,y2,c);
}
...
};

#!/usr/bin/perl
use gd;
$im = new gdImage(400,400);
$black = $im->colorAllocate(0,0,0);
$white = $im->colorAllocate(255,255,255);
$im->line(20,50,180,140,$white);
...

3.8 Access Control and Naming

// Create read-only variables
%readonly
int foo;         // Read-only
double bar;      // Read-only
%readwrite

// Create read-only class members
class List {
...
%readonly
    int length;  // Read-only member
%readwrite
...
}

Another common problem is changing the name of various C declarations. For example, a C function name may conflict with an existing Perl keyword or subroutine. To fix this problem, the %name directive can be used. For example,

%name(cpack) void pack(Object *);

%rename pack cpack;

%name(Image) class gdImage {
...
}

3.9 Exception Handling

%except(perl5) {
   errno = 0;
   $function
   if (errno) {
      die(strerror(errno));
   }
}

While catching errors in the C library has been illustrated, exception handlers can also be written to catch C++ exceptions or to use any special purpose error handling code that might be present in an application.

3.10 Typemaps

3.10.1 Example: Output Values

void
imagesize(gdImagePtr im, int *w, int *h) {
    *w = gdImageSX(im);
    *h = gdImageSY(im);
}

$wptr = new_integer();  # Create an 'int *'
$hptr = new_integer();
imagesize($im, $wptr, $hptr);  
$w = integer_value($wptr); # Dereference
$h = integer_value($hptr);
delete_integer($wptr);     # Clean up
delete_integer($hptr);

%include typemaps.i
void imagesize(gdImagePtr im, int *OUTPUT,
               int *OUTPUT);

($w,$h) = imagesize($im); 

%include typemaps.i
void
imagesize(gdImagePtr im, int *REFERENCE,
          int *REFERENCE);

# Return values in $w and $h
imagesize($im,\$w,\$h); 

3.10.2 Creating New Typemaps

To illustrate, consider the gd example. In the original interface file, two functions were included to open and close files. These were required because SWIG normally maps all pointers (including files) into blessed references. Since a blessed reference is not the same as a Perl file handle, it is not possible to pass Perl files to functions expecting a FILE *. However, this is easily changed with a typemap as follows:

%typemap(perl5,in) FILE * {
   $target = IoIFP(sv_2io($source));
}

open(OUT,">test.gif") || die "error!\n";

# Much better than before
gd::gdImageGif($im,*OUT);

%typemap(perl5,ignore)
int *OUTPUT(int temp) {
  $target = &temp;
}
%typemap(perl5,argout) int *OUTPUT {
  if (argvi >= items) {
     EXTEND(sp,1);
  }
  $target = sv_newmortal();
  sv_setiv($target,(IV) *($source));
  argvi++;
}

The C code supplied in each typemap is placed in a private scope that is not visible to any other typemaps or other parts of a wrapper function. This allows different typemaps to be used simultaneously--even if they define variables with the same names. This also allows the same typemap to be used more once in the same wrapper function. For example, the previous section used the int *OUTPUT typemap twice in the same function without any adverse side-effects.

3.10.3 Typemap Libraries

// check.i
// typemaps for checking argument values
%typemap(perl5,check) Number POSITIVE {
    if ($target <= 0)
       croak("Expected a positive value");
}

%typemap(perl5,check) Pointer *NONNULL {
    if ($target == NULL)
       croak("Received a NULL pointer!");
}
...

%include check.i

// Force 'double px' to be positive
%apply Number Positive { double px };

// Force these pointers to be NON-NULL
%apply Pointer NONNULL { FILE *, 
                         Vector *,
                         Matrix *,
                         gdImage * };

// Now some functions
double log(double px);   // 'px' positive
double dot_product(Vector *, Vector *);
...

3.11 Other SWIG Features

3.12 Putting it All Together

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

// Make FILE * work
%typemap(perl5,in) FILE * {
   $target = IoIFP(sv_2io($source));
}

// Grab the gd.h header file
%include "gd.h"

// Extend the interface a little bit
%addmethods gdImage {
gdImage(int w, int h) {
    return gdImageCreate(w,h);
}
~gdImage() {
    gdImageDestroy(self);
}
... etc ...
};

%addmethods gdPoint {
... etc ...
}

// Wrap the fonts (readonly variables)
%readonly
%include "gdfontt.h"
%include "gdfonts.h"
%include "gdfontmb.h"
%include "gdfontl.h"
%include "gdfontg.h"
%readwrite

use gd;

$im = new gdImage(100,100);
$white= $im->colorAllocate(255,255,255);
$black= $im->colorAllocate(0,0,0);
$red= $im->colorAllocate(255,0,0);
$blue= $im->colorAllocate(0,0,255);
$im->transparentcolor($white);
$im->interlaced(1);
$im->rectangle(0,0,99,99,$white);
$im->arc(50,50,95,75,0,360,$blue);
$im->fill(50,50,$red);
open(IMG, ">test.gif");
$im->gif(*IMG);
close(IMG);

4 Interface Building Strategies

4.1 Wrapping an Existing Program

1. Locate header files and other sources of C declarations.
2. Copy header files to interface files.
3. Edit the interface file and add SWIG directives.
4. Remove or rewrite the application's main() function if necessary.
5. Run SWIG, compile, and link into a Perl extension module.

4.2 Evolutionary Interface Building

4.3 Traps and Pitfalls

void foo() {
   static int called = 0;
   if (called) return;
   ...
   called = 1;
}

%except(perl5) {
   static int called = 0;
   if (called) 
         croak("Already executed!\n");
   $function
   called = 1;
}
// List all non-reentrant functions
void foo();
...
// Clear the exception handler
%except(perl5);

void geterror(char *msg) {
     strcpy(msg,strerror(errno));
}

// Use a temporary array for the result
%typemap(perl5,ignore)
char *msg (char temp[512]) {
    $target = temp;
}
// Copy the output into a new Perl scalar
%typemap(perl5,argout) char *msg {
  if (argvi >= items) {
     EXTEND(sp,1);
  }
  $target = sv_newmortal();
  sv_setpv($target,$source);
  argvi++;
}

5 Applications

5.1 Electronic CAD

The core components in Badger are constructed in C++ and are delivered as a set of shared (dynamically loaded) libraries. The libraries are not directly linked into an executable program. Instead, each library comes with an extension language (EL) interface that is generated by SWIG, allowing the library to be used within a Perl program [footnote: For now, Perl is the only supported extension language. Tcl and Java will be supported in the future]. The combination of a powerful EL and well-tuned, application-specific software results in a system that is potent, flexible, and easy to use.

For the most part, SWIG is used in a ``normal'' fashion: a description of the classes contained within a library is presented to SWIG, and it generates an EL interface that allows the code within that library to be accessed from an EL. There are two interesting facets to the use of SWIG within Badger: the use of ``smart references,'' and the use of callbacks from C++ to the EL,

5.1.1 Smart References

It is possible to design Badger so that the extension language has complete control over the lifetime of all the objects within the system. Unfortunately, this approach results in a system that is too closely tied to the implementation of a particular language, and adding a new extension language to the mix is difficult. An alternate solution that is simple to implement and is portable, is to introduce ``smart references'' (also called proxies) into the design [5, pg. 207]. In effect, a smart reference is an object that has the same set of operations as a ``real'' object, but the smart reference's implementation consists solely of a single pointer to a ``real'' object of the appropriate type.

The extension language interfaces within Badger have been crafted so that the extension language manipulates smart references and that the lifetime of a smart reference is completely under the control of the extension language. Under most circumstances, the extension language performs an operation on the smart reference, and the smart reference then attempts to transfer the operation to the real object. If the real object has been destroyed then the smart reference will have been invalidated (it points to nil). In this case, the operation is aborted and, if possible, an exception is raised in the extension language. Badger contains the necessary machinery to invalidate any smart references that point to an object being destroyed.

Modern C++ compilers, with their support for templates, run-time type identification, and so forth, provide the means to automatically construct smart reference classes. For a variety of reasons, we are not able to always utilize modern compilers. Hence, we have created the implementations of the smart references manually, which is a tedious process. Fortunately, this task can be mostly automated by creating our own code generator as part of SWIG. This is a simple matter, as SWIG is a modular software system.

5.1.2 Callbacks

• Define a function.
• Register the function.
• Perform some operation that causes the registered function to be invoked.

Badger provides a number of classes derived from Trigger that specialize its behavior for certain extension languages, for C++, or for an object request broker. For example, the Perl5Trigger class is derived from Trigger and it specializes its base class by storing a pointer to a Perl function reference (an SV*), and by providing the machinery needed to invoke that Perl function.

For example, consider the following Perl fragment:

sub MyFcn {
  my $EventName = shift;
  my $Object = shift;
  # ... rest of function here.
}
my $Object = BadgerFunction(....);
my $Name = "Can't find file";
Badger::RegisterByObject($Name, 
                     $Object, \&MyFcn);
$Object->ReadFile("A bogus file name");

The RegisterByObject() function is responsible for creating an object of the Perl5Trigger class, and for creating the association between the Perl5Trigger, the event name, and the object receiving the event. There is a bit of typemap trickery involved when intercepting the arguments from Perl:

%typemap(perl5,in) SV* pFcn {
  if (!SvROK($source))
    croak("Expected a reference.\n");
  $target = SvRV($source);
}
void
RegisterByObject(const char* pcEventName,
                 Ref* pRef, SV* pFcn);

bool
Perl5Trigger::
Invoke(const char* pcEventName,
       void* pObject,
       const char* pcTypeName) {
  dSP;
  ENTER;
  SAVETMPS;
  PUSHMARK(sp);
  SV* pSV = sv_newmortal();
  sv_setpv(pSV, (char*) pcEventName);
  XPUSHs(pSV);
  pSV = sv_newmortal();
  sv_setref_pv(pSV, (char*) pcTypeName,
               pObject);
  XPUSHs(pSV);
  pSV = sv_newmortal();
  sv_setpv(pSV, (char*) pcTypeName);
  XPUSHs(pSV);
  PUTBACK;
  int n = perl_call_sv(this->pPerl5Fcn, 
               G_SCALAR); 
  SPAGAIN;
  if (n == 1)
    n = POPi;
  PUTBACK;
  FREETMPS;
  LEAVE;
  return n == 0 ? false : true;
}

5.1.3 Benefits And Limitations

• Not counting custom code (e.g., language-specific callbacks), an extension language interface can be developed in a day, compared with weeks for a hand-crafted approach.
• SWIG supports the use of multiple extension languages with ease.
• The resulting solution is flexible, and the results can be tailored to meet the needs of complex applications (e.g., callbacks, smart references, and so on).

5.2 TCAP and SCCP from HP OpenCall

To solve this problem, SWIG can be used to incorporate libraries into Perl extension modules where test cases can be implemented as Perl scripts. As a result, the compile-execute cycle is no longer a problem and Perl scripts can be used to implement common parts of various test cases.

This section describes the integration of Perl with an API that is part of a HP OpenCall telecom product developed at HP Grenoble. The API provides access to the TCAP and SCCP layers of the SS7 protocol and consists of about 20 function and 60 structure declarations. Furthermore, most function parameters are pointers to deeply nested structures such as follows:

typedef enum {
  ...
} tc_address_nature;

typedef struct  {
  ...
  tc_address_nature  nature;
  ...
} tc_global_title;

typedef struct tc_address_struct {
  ...
  tc_global_title    gt;
  ...
} tc_address;

5.2.1 Creating the SWIG Interface

As part of the interface building process, header files were to be included directly into interface files. This is easily done using the %include directive, but a number of problematic nested structure declarations had to be fixed. For example,

struct tcStat {
  ...
  union {
    ...
    struct stat_p_abort {
      int value;
      tc_p_abort_cause  p_abort;
    } abort;
    ...
  } p;
} tc_stat;

typedef struct {
  int value;
  tc_p_abort_cause  p_abort;
} tc_stat_abort;

struct TcStat {
  ...
  tc_stat_abort  abort;
  ...
};

In addition to splitting, a number of structures in the header files were to be hidden from the SWIG compiler. While this could be done using a simple #ifndef SWIG in the code, this could potentially result in a huge customer problem if they also defined a SWIG macro in their compilation process. Therefore, conditional compilation was implemented using some clever C comments that were parsed by vpp (See the Text::Vpp module) during the build of the SWIG interface. For example,

/*
HP reserved comment
@if not $_hp_reserved_t
*/
typedef struct {
  int           length;
  unsigned char datas[MAX_ABORT_LEN];
} tc_u_abort;
/*
@endif
 */

5.2.2 Shadow Classes

tc_global_title *
tc_address_gt_get(tc_address *);

tc_address_nature
tc_global_title_nature_set(
   tc_global_title *t,
   tc_address_nature val);

$param = new_tc_address();
tc_global_title_nature_set(
    tc_address_gt_get($param),
    $value);

$parm = new tc_address;
$param->{gt}{nature} = $value;

5.2.3 Customization With Typemaps

typedef struct {
    ...
    tc_u_abort  abort_reason;
    ...
} tc_dialog_portion;

my $dialog = new tc_dialog_portion;
$dialog->{abort_reason} = '0f456A';

# Or
print "User abort reason is \
$dialog->{abort_reason} \n";

%typemap (perl5,in) tc_u_abort *
($basetype temp)
{
  int i;
  STRLEN len;
  short tmp;
  char *str;
  $target = &temp;

  /* convert  scalar to char* */
  str = SvPV($source,len);
  /* check if  even # of char */
  if ( (len % 2) != 0 ) {
    croak("Uneven # of char");
  }
  /* set length field */
  $target->length=(len/2);
  if ((len/2)>(sizeof($basetype)-1))
  {
    croak("Too many bytes in value\n");
  }
  for (i=0;i<$target->length;i++)
  {
    if (sscanf(str,"%2hx", &tmp) != 1 )
      croak("sscanf failed on %s, \
             is it hexa ?\n",str);
      $target->datas[i] = tmp;
      str+=2;
  }
}

%typemap (perl5,out) tc_u_abort *
{
  int i;
  $target=newSVpvf("%x",$source->datas[0]);

  for (i=1; i< $source->length; i++) {
    sv_catpvf($target,"%x",
              $source->datas[i]);
  }
  argvi ++;
}

# $address is an ordinary perl hash
# $address will be used as an array
$address->{pc} = 10; 
$address->{ssn}= 12;
...
SCCP_oamcmd($cnxId, $time, undef, $address,
            $command, $cmd_parms);

%typemap (perl5,in) SccpOamAddress* {
  HV* passedHash;
  SV** valuePP;
  SccpOamAddress tempAddress;
  if (!SvOK($source)) {
      /* we were passed undef */
      tempAddress[0] = 0;
      tempAddress[1] = 0;
  } else {
    if (!SvROK($source))
      croak("Not a reference\n");
    if (SvTYPE(SvRV($source)) != SVt_PVHV)
      croak("Not a hash reference\n");

    passedHash = (HV*) SvRV($source);
    valuePP=hv_fetch(passedHash,"ssn",3,0);

    if (*valuePP == NULL)
      croak("Missing 'ssn' key\n");
    tempAddress[1] = SvIV(*valuePP);
    valuePP=hv_fetch(passedHash,"pc",2,0);
    if (*valuePP == NULL)
      croak("Missing 'pc' key\n");
    tempAddress[0] = SvIV(*valuePP);
  }
  $target = &tempAddress;
}

/* SccpOamAddress is returned as 
   {'ssn'=>ssn_value, 'pc'=>pc_value} */
%typemap (perl5,out) SccpOamAddress* {
  HV* passedHash;
  SV* theSsn;
  SV* thePc;

  thePc  = newSViv((*$source)[0]);
  theSsn = newSViv((*$source)[1]);
  passedHash = newHV();
  hv_store(passedHash,"ssn",3,theSsn,0);
  hv_store(passedHash,"pc",2,thePc,0);
  $target = newRV_noinc((SV*) passedHash);
  argvi ++;
}

5.2.4 Statistics

5.2.5 Results

• The interface files are quite short so if they are well documented, a new SWIG user should not have any major problems maintaining them.
• A new version of the API is wrapped with a 'make' command, so there is no need to edit any file. In most cases the interface files can remain unmodified, provided there are no weird constructs introduced in the new version of the API.
• New comments added in the header files will be automatically added in the documentation files generated by SWIG.
• If necessary, new helper functions may be added in the .i files without impacting other parts of the code or typemaps. This allows a new user to do it without reading the whole SWIG manual.
• Typemaps that deal with basic types or simple structures are reusable and can be used with other APIs.

6 Limitations

• Variable length arguments (...)
• Pointers to functions.
• Templates.
• Overloaded functions and operators.
• C++ Namespaces.
• Nested class definitions.

A closely related problem is that certain C/C++ programs are not easily scripted. For example, programs that make extensive use of advanced C++ features such as templates, smart pointers, and overloaded operators can be extremely troublesome to incorporate into Perl. This is especially the case for C++ programs that override the standard behavior of pointers and deferencing operations---operations that are used extensively by SWIG generated wrapper code.

In addition, SWIG does not provide quite as much flexibility as xsubpp and other Perl specific extension building tools. In order to be general purpose, SWIG hides many of the internal implementation details of each scripting language. As a result, it can be difficult to accomplish certain tasks. For example, one such situation is the handling of functions where arguments are implicitly related to each other as follows:

void foo(char *str, int len) {
   // str = string data
   // len = length of string data   
   ...
}

Finally, SWIG is still somewhat immature with respect to its overall integration with Perl. For example, SWIG does not fully support Perl's package and module naming system. In other words, SWIG can create a module ``Foo'', but can't create a module ``Foo::Bar.'' Likewise, SWIG does not currently utilize MakeMaker and other utilities (although users have successfully used SWIG with such tools). In addition, some users have reported occasional problems when SWIG modules are used with the Perl debugger and other tools.

7 Future Directions

8 Acknowledgments

9 Availability

www.perl.com/CPAN/authors/Dave_Beazley.

Additional information is also available on the SWIG homepage at www.swig.org. An active mailing list of several hundred subscribers is also available.

Bibliography

[2] Scott Bolte. SWIG. The Perl Journal, 2(4):26-31, Winter 1997.

[3] D.M. Beazley. SWIG and Automated C/C++ Scripting Extensions. Dr. Dobb's Journal, (282):30-36, Feb 1998.

[4] D.M. Beazley, SWIG Users Manual. Technical Report UUCS-98-012, University of Utah, 1998.

[5] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, Design Patterns. Addison-Wesley, 1995.