Perl-C/C++ Integration with Swig

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

Perl-C/C++ Integration with Swig

Dave BeazleyDepartment of Computer Science

University of ChicagoChicago, IL 60637

[email protected]

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 xsubppPerl 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

main()

FunctionsVariablesObjects

Header file

extern int foo(int n);extern double bar;struct Person { char *name; char *email;};

%module myprog%{#include "myprog.h"%}extern int foo(int n);extern double bar;struct Person { char *name; char *email;};

Swig Interface

FunctionsVariablesObjects

Perl

WrappersSwig

Interesting C Program


Swig OutputSwig 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

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.

int foo(int, int);double Global;#define BAR 5.5...

$r = foo(2,3);$Global = 3.14;print $BAR;...

C Code Perl


Interface FilesAnnotated Header Files

Module name

Preamble• Inclusion of header files• Support code• Same idea as in yacc/bison

Public Declarations• Put anything you want in Perl here• Converted into wrappers.• Usually a subset of a header file.

Note : Can use header files• May need conditional compilation.

%module myprog

%{#include "myprog.h"%}

extern int foo(int n);extern double bar;struct Person { char *name; char *email;};


Supported C/C++ FeaturesFunctions, 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.


PointersSwig 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 ClassesStructures and classes can be hidden behind a Perl class:

class Foo {public: int x; Foo(); ~Foo(); int bar(int); ...}

Foo *new_Foo();void delete_Foo(Foo *f);int Foo_x_get(Foo *f);int Foo_x_set(Foo *f, int x);int Foo_bar(Foo *f, int);...

package Foo;sub new { return new_Foo();}sub DESTROY { delete_Foo();}...etc...

$f = new Foo;$f->bar(3);$f->bar{’x’} = 7;del $f;

C/C++ struct or class C accessor functions

Perl wrappers Use from a Perl script


Swig ApplicationsUser 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 ProblemsSwig 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 ProblemsSwig doesn’t understand certain declarations

• Can remove with conditional compilation or comments

Example:

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.

int foo(char *fmt, ...);

int bar(int (*func)(int));

#define Width(im) (im->width)

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

#ifndef SWIGint bar(int (*func)(int));#endif

int Width(Image *im);


Advanced FeaturesTypemaps

• 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 ExampleProblem : Output valuesvoid 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 HandlingProblem : Converting C errors into Perl errorsint 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 ExtensionAn interesting hack to attach methods to structs/classestypedef struct { int width; int height; ...} Image;

%addmethods Image { Image(int w, int h) { return CreateImage(w,h); } ~Image() { free(self); } void plot(int x, int y, int c) { ImagePlot(self,x,y,z); } ...}

$im = new Image;$im->plot(30,40,1);

print $im->{’width’};etc ...


LimitationsParsing 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 PlansSwig1.1 is maintained, but is not the focus of development

• Daily maintenance builds athttp://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.


AvailabilitySwig 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

Technology

Transcript of Perl-C/C++ Integration with Swig