Presentation from O'Reilly Open Source Conference 3.0, 1999.

1. 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

2. Roadmap
What is Swig?
How does it work?
Why would you want to use it?
Advanced features.
Limitations and rough spots.
Future plans.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

3. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

4. 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).
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

5. 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;
};
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

6. 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)
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

7. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

8. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

9. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

10. 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...
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

11. 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...
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

12. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

13. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

14. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

15. 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...
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

16. 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).
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

17. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

18. 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);
}
...
}
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

19. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

20. 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.
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999

21. 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
O’Reilly Open Source Conference 3 0 - Swig - August 23 1999