SWIG Users Guide SWIG and Perl5 115

In this chapter, we discuss SWIG’s support of Perl5. While the Perl5 module is one of the earliest SWIG modules, it has continued to evolve and has been improved greatly with the help of SWIG users. For the best results, it is recommended that SWIG be used with Perl5.003 or later. Earlier versions are problematic and SWIG generated extensions may not compile or run correctly.

Preliminaries

In order for this section to make much sense, you will need to have Perl5.002 (or later) installed on your system. You should also determine if your version of Perl has been configured to use dynamic loading or not. SWIG will work with or without it, but the compilation process will be different.

Running SWIG

To build a Perl5 module, run swig using the -perl5 option as follows :

swig -perl5 example.i

This will produce 3 files. The first file, example_wrap.c contains all of the C code needed to build a Perl5 module. The second file, example.pm contains supporting Perl code needed to properly load the module into Perl. The third file will be a documentation file (the exact filename depends on the documentation style). To finish building a module, you will need to compile the file example_wrap.c and link it with the rest of your program (and possibly Perl itself). There are several methods for doing this.

Getting the right header files

In order to compile, you will need to use the following Perl5 header files :

#include “Extern.h” #include “perl.h” #include “XSUB.h”

These are usually located in a directory like this

/usr/local/lib/perl5/arch-osname/5.003/CORE

The SWIG configuration script will try to find this directory, but it’s not entirely foolproof. You may have to dig around yourself.

Version 1.1, June 24, 1997

Compiling a dynamic module

To compile a dynamically loadable module, you will need to do something like the following,

%gcc example.c

%gcc example_wrap.c -I/usr/local/lib/perl5/arch-osname/5.003/CORE -Dbool=char -c

The name of the shared object file must match the module name used in the SWIG interface file. If you used ‘%module example’, then the target should be named ‘example.so’, ‘example.sl’, or the appropriate name on your system (check the man pages for the linker).

Unfortunately, the process of building dynamic modules varies on every single machine. Both the C compiler and linker may need special command line options. SWIG tries to guess how to build dynamic modules on your machine in order to run its example programs. Again, the configure script isn’t foolproof .

Building a dynamic module with MakeMaker

It is also possible to use Perl to build dynamically loadable modules for you using the MakeMaker utility. To do this, write a simple Perl script such as the following :

# File : Makefile.PL use ExtUtils::MakeMaker;

Now, to build a module, simply follow these steps :

%perl Makefile.PL

%make

%make install

This is the preferred approach if you building general purpose Perl5 modules for distribution. More information about MakeMaker can be found in “Programming Perl, 2nd ed.” by Larry Wall, Tom Christiansen, and Randal Schwartz.

Building a static version of Perl

If you machine does not support dynamic loading, or if you’ve tried to use it without success, you can build a new version of the Perl interpreter with your SWIG extensions added to it. To build a static extension, you first need to invoke SWIG as follows :

% swig -perl5 -static example.i

By default SWIG includes code for dynamic loading, but the -static option takes it out.

Next, you will need to supply a main() function that initializes your extension and starts the Perl interpreter. While, this may sound daunting, SWIG can do this for you automatically as follows :

Version 1.1, June 24, 1997

%module example

extern double My_variable; extern int fact(int);

// Include code for rebuilding Perl %include perlmain.i

The same thing can be accomplished by running SWIG as follows :

% swig -perl5 -static -lperlmain.i example.i

The permain.i file inserts Perl’s main() function into the wrapper code and automatically initializes the SWIG generated module. If you just want to make a quick a dirty module, this may be the easiest way. By default, the perlmain.i code does not initialize any other Perl extensions. If you need to use other packages, you will need to modify it appropriately. You can do this by just copying perlmain.i out of the SWIG library, placing it in your own directory, and modifying it to suit your purposes.

To build your new Perl executable, follow the exact same procedure as for a dynamic module, but change the link line as follows :

% ld example.o example_wrap.o -L/usr/local/lib/perl5/arch/5.003/CORE \ -lperl -lsocket -lnsl -lm -o myperl

This will produce a new version of Perl called myperl. It should be functionality identical to Perl with your C/C++ extension added to it. Depending on your machine, you may need to link with additional libraries such as -lsocket, -lnsl, -ldl, etc...

Compilation problems and compiling with C++

In some cases, you may get alot of error messages about the ‘bool’ datatype when compiling a SWIG module. If you experience this problem, you can try the following :

•Use -DHAS_BOOL when compiling the SWIG wrapper code

•Or use -Dbool=char when compiling.

Compiling dynamic modules for C++ is also a tricky business. When compiling C++ modules, you may need to link using the C++ compiler such as :

unix > c++ -shared example_wrap.o example.o -o example.so

It may also be necessary to link against the libgcc.a, libg++.a, and libstdc++.a libraries (assuming g++). C++ may also complain about one line in the Perl header file “perl.h” and the invalid use of the “explicit” keyword. To work around this problem, put the option -Dex- plicit= in your compiler flags.

If all else fails, put on your wizard cap and start looking around in the header files. Once you’ve figured out how to get one module to compile, you can compile just about all other modules.

Version 1.1, June 24, 1997