Perl-C/C++ Integration with Swig

Perl-C/C++ Integration with Swig

Dave Beazley
Department of Computer Science
University of Chicago
Chicago, IL 60637
beazley@cs.uchicago.edu

August 23, 1999

O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

Roadmap

What is Swig?

How does it work?

Why would you want to use it?

Advanced features.

Limitations and rough spots.

Future plans.


What is Swig?
It’s a compiler for connecting C/C++ with interpreters

General idea:
• Take a C program or library
• Grab its external interface (e.g., a header file).
• Feed to Swig.
• Compile into an extension module.
• Run from Perl (or Python, Tcl, etc...)
• Life is good.


Swig, h2xs and xsubpp
Perl already has extension building tools
• xsubpp
• h2xs
• Makemaker
• Primarily used for extension building and distribution.

Why use Swig?
• Much less internals oriented.
• General purpose (also supports Python, Tcl, etc...)
• Better support for structures, classes, pointers, etc...

Also...
• Target audience is primarily C/C++ programmers.
• Not Perl extension writers (well, not really).


How does it work?
Typical C program Header file
main() extern int foo(int n);
extern double bar;
Functions struct Person {
Variables char *name;
Objects char *email;
};

Interesting C Program Swig Interface
Perl %module myprog
Swig
%{
Wrappers #include "myprog.h"
%}
Functions extern int foo(int n);
Variables extern double bar;
Objects struct Person {
char *name;
char *email;
};


Swig Output
Swig converts interface files into C wrapper code
• Similar to the output of xsubpp.
• It’s nasty and shouldn’t be looked at.

Compilation steps:
• Run Swig
• Compile the wrapper code.
• Link wrappers and original code into a shared library.
• Cross fingers.

If successful...
• Program loads as a Perl extension.
• Can access C/C++ from Perl.
• With few (if any) changes to the C/C++ code (hopefully)


Example
C Code Perl
int foo(int, int); $r = foo(2,3);
double Global; $Global = 3.14;
#define BAR 5.5 print $BAR;
... ...

Perl becomes an extension of the underlying C/C++ code
• Can invoke functions.
• Modify global variables.
• Access constants.

Almost anything that can be done in C can be done from Perl
• We’ll get to limitations a little later.


Interface Files
Annotated Header Files

Module name %module myprog

Preamble %{
• Inclusion of header files #include "myprog.h"
• Support code %}
• Same idea as in yacc/bison

Public Declarations extern int foo(int n);
• Put anything you want in Perl here
extern double bar;
• Converted into wrappers. struct Person {
• Usually a subset of a header file.
char *name;
char *email;
Note : Can use header files };
• May need conditional compilation.


Supported C/C++ Features
Functions, variables, and constants
• Functions accessed as Perl functions.
• Global variables mapped into magic Perl variables.
• Constants mapped into read-only variables.

All C/C++ datatypes supported except:
• Pointers to functions and pointers to arrays (can fix with a typedef).
• long long and long double
• Variable length arguments.
• Bit-fields (can fix with slight modifications in interface file).
• Pointers to members.

Structures and classes
• Access to members supported through accessor functions.
• Can wrap into Perl "classes."
• Inheritance (including multiple inheritance).
• Virtual and static members.


Pointers
Swig allows arbitrary C pointers to be used
• Turned into blessed references

Pointers are opaque
• Can freely manipulate from Perl.
• But can’t peer inside.

Type-checking
• Pointers encoded with a type to perform run-time checks.
• Better than just casting everything to void * or int.

Works very well with C programs
• Structures, classes, arrays, etc...
• Besides, you can never have too many pointers...


Shadow Classes
Structures and classes can be hidden behind a Perl class:
C/C++ struct or class C accessor functions
class Foo { Foo *new_Foo();
public: void delete_Foo(Foo *f);
int x; int Foo_x_get(Foo *f);
Foo(); int Foo_x_set(Foo *f, int x);
~Foo(); int Foo_bar(Foo *f, int);
int bar(int); ...
...
}

Perl wrappers Use from a Perl script
package Foo; $f = new Foo;
sub new { $f->bar(3);
return new_Foo(); $f->bar{’x’} = 7;
} del $f;
sub DESTROY {
delete_Foo();
}
...etc...


Swig Applications
User interfaces
• Use Perl, Python, or Tcl as the interface to a C program.
• This is particularly useful in certain applications.

Rapid prototyping and debugging of C/C++
• Use scripts for testing.
• Prototype new features.

Systems integration
• Use Perl, Python, or Tcl as a glue language.
• Combine C libraries as extension modules.

The key point:
• Swig can greatly simplify these tasks.


Interface Building Problems
Swig attempts to be completely automated.
• "Wrap it and forget it"

Problem : C/C++ code varies widely (and may be a mess)
• Pointer ambiguity (arrays, output values, etc...).
• Preprocessor macros.
• Error handling (exceptions, etc...)
• Advanced C++ (templates, overloading, etc...)

Other problems
• A direct translation of a header file may not work well.
• Swig only understands a subset of C.
• May want to interface with Perl data structures.


Parsing Problems
Swig doesn’t understand certain declarations
• Can remove with conditional compilation or comments

Example:
int foo(char *fmt, ...); // int foo(char *fmt, ...);

int bar(int (*func)(int)); #ifndef SWIG
int bar(int (*func)(int));
#define Width(im) (im->width) #endif

int Width(Image *im);

A Swig interface doesn’t need to match the C code.
• Can cut out unneeded parts.
• Play games with typedef and macros.
• Write helper functions.


Advanced Features
Typemaps
• A technique for modifying Swig’s type handling.

Exception Handling
• Converting C/C++ errors into Perl errors.

Class and structure extension
• Adding new methods to structures and classes
• Building O-O interfaces to C programs.

This is going to be a whirlwind tour...


Typemap Example
Problem : Output values
void getsize(Image *im, int *w, int *h) {
*w = im->width;
*h = im->height;
}

Solution: Typemap library
%include typemaps.i
%apply int *OUTPUT { int *w, int *h };
...
void getsize(Image *im, int *w, int *h);

From Perl:
($w,$h) = getsize($im);

Note: There is a lot of underlying magic here (see docs).


Exception Handling
Problem : Converting C errors into Perl errors
int foo() {
...
throw Error;
...
};

Solution (place in an interface file):
%except(perl5) {
$function
if (Error) {
croak("You blew it!");
}
}

Exception code gets inserted into all of the wrappers.


Class Extension
An interesting hack to attach methods to structs/classes
typedef struct {
int width;
int height;
...
} Image;
$im = new Image;
%addmethods Image { $im->plot(30,40,1);
Image(int w, int h) {
return CreateImage(w,h); print $im->{’width’};
} etc ...
~Image() {
free(self);
}
void plot(int x, int y, int c) {
ImagePlot(self,x,y,z);
}
...
}


Limitations
Parsing capability is limited
• Some types don’t work:
int (*func[10])(int, double);
int *const a;
int **&a;
• No macro expansion (Swig1.1)
• A number of advanced C++ features not supported.

Not all C/C++ code is easily scriptable
• Excessive complexity.
• Abuse of macros and templates.

Better integration with Perl
• Support for MakeMaker and other tools.
• Windows is still a bit of a mess.

Future Plans
Swig1.1 is maintained, but is not the focus of development
• Daily maintenance builds at
http://swig.cs.uchicago.edu/SWIG

Swig2.0
• A major rewrite and reorganization of Swig.
• Primary goal is to make Swig more extensible.

Highlights
• Better parsing (new type system, preprocessing, etc...)
• Plugable components (code generators, parsers, etc...)
• Substantially improved code generation.
• Release date : TBA.


Availability
Swig is free.
• www.swig.org (Primary)
• swig.cs.uchicago.edu (Development)
• CPAN

Compatibility
• Most versions of Perl (may need latest Swig however).
• Unix, Windows.

Acknowledgments
• David Fletcher, Dominique Dumont, and Gary Holt.
• Swig users who have contributed patches.
• University of Utah
• Los Alamos National Laboratory


Perl-C/C++ Integration with Swig

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (6)

Similar to Perl-C/C++ Integration with Swig

Similar to Perl-C/C++ Integration with Swig (20)

Recently uploaded

Recently uploaded (20)

Perl-C/C++ Integration with Swig