Caution: This chapter is under repair!
This chapter describes SWIG's support of Perl5. Although 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 Perl 5.8 or later. We're no longer testing regularly with older versions, but Perl 5.6 seems to mostly work, while older versions don't.
To build Perl extension modules, SWIG uses a layered approach. At the lowest level, simple procedural wrappers are generated for functions, classes, methods, and other declarations in the input file. Then, for structures and classes, an optional collection of Perl proxy classes can be generated in order to provide a more natural object oriented Perl interface. These proxy classes simply build upon the low-level interface.
In describing the Perl interface, this chapter begins by covering the essentials. First, the problem of configuration, compiling, and installing Perl modules is discussed. Next, the low-level procedural interface is presented. Finally, proxy classes are described. Advanced customization features, typemaps, and other options are found near the end of the chapter.
To build a Perl5 module, run SWIG using the -perl option as follows:
swig -perl example.i
This produces two 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.
To build the module, you will need to compile the file example_wrap.c and link it with the rest of your program.
In order to compile, SWIG extensions need the following Perl5 header files:
#include "Extern.h" #include "perl.h" #include "XSUB.h"
These are typically located in a directory like this
/usr/lib/perl/5.14/CORE
The SWIG configuration script automatically tries to locate this directory so that it can compile examples. However, if you need to find out where the directory is located, an easy way to find out is to ask Perl itself:
$ perl -e 'use Config; print "$Config{archlib}\n";'
/usr/lib/perl/5.14
The preferred approach to building an extension module is to compile it into a shared object file or DLL. Assuming you have code you need to link to in a file called example.c, you will need to compile your program using commands like this (shown for Linux):
$ swig -perl example.i $ gcc -fPIC example.c $ gcc -fPIC -c example_wrap.c -I/usr/lib/perl/5.14/CORE -Dbool=char $ gcc -shared example.o example_wrap.o -o example.so
The exact compiler options vary from platform to platform. SWIG tries to guess the right options when it is installed. Therefore, you may want to start with one of the examples in the SWIG/Examples/perl5 directory. If that doesn't work, you will need to read the man-pages for your compiler and linker to get the right set of options. You might also check the SWIG Wiki for additional information.
When linking the module, 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 dynamic module name on your system.
It is also possible to use Perl to build dynamically loadable modules for you using the MakeMaker utility. To do this, write a Perl script such as the following:
# File : Makefile.PL use ExtUtils::MakeMaker; WriteMakefile( `NAME' => `example', # Name of package `LIBS' => [`-lm'], # Name of custom libraries `OBJECT' => `example.o example_wrap.o' # Object files );
Now, to build a module, simply follow these steps:
$ perl Makefile.PL $ make $ make install
If you are planning to distribute a SWIG-generated module, this is the preferred approach to compilation. More information about MakeMaker can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, and Randal Schwartz.
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 -perl -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:
%module example
%inline %{
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 -perl -static -lperlmain.i example.i
The perlmain.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 to something like this:
$ gcc example.o example_wrap.o -L/usr/lib/perl/5.14/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.
To use the module, simply use the Perl use statement. If all goes well, you will be able to do this:
$ perl use example; print example::fact(4),"\n"; 24
A common error received by first-time users is the following:
use example; Can't locate example.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at - line 1. BEGIN failed--compilation aborted at - line 1.
This error is almost caused when the name of the shared object file you created doesn't match the module name you specified with the %module directive.
A somewhat related, but slightly different error is this:
use example; Can't find 'boot_example' symbol in ./example.so at - line 1 BEGIN failed--compilation aborted at - line 1.
This error is generated because Perl can't locate the module bootstrap function in the SWIG extension module. This could be caused by a mismatch between the module name and the shared library name. However, another possible cause is forgetting to link the SWIG-generated wrapper code with the rest of your application when you linked the extension module.
Another common error is the following:
use example; Can't load './example.so' for module example: ./example.so: undefined symbol: Foo at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169. at - line 1 BEGIN failed--compilation aborted at - line 1.
This error usually indicates that you forgot to include some object files or libraries in the linking of the shared library file. Make sure you compile both the SWIG wrapper file and your original program into a shared library file. Make sure you pass all of the required libraries to the linker.
Sometimes unresolved symbols occur because a wrapper has been created for a function that doesn't actually exist in a library. This usually occurs when a header file includes a declaration for a function that was never actually implemented or it was removed from a library without updating the header file. To fix this, you can either edit the SWIG input file to remove the offending declaration or you can use the %ignore directive to ignore the declaration. Better yet, update the header file so that it doesn't have an undefined declaration.
Finally, suppose that your extension module is linked with another library like this:
$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
-o example.so
If the foo library is compiled as a shared library, you might get the following error when you try to use your module:
use example; Can't load './example.so' for module example: libfoo.so: cannot open shared object file: No such file or directory at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169. at - line 1 BEGIN failed--compilation aborted at - line 1. >>>
This error is generated because the dynamic linker can't locate the libfoo.so library. When shared libraries are loaded, the system normally only checks a few standard locations such as /usr/lib and /usr/local/lib. To get the loader to look in other locations, there are several things you can do. First, you can recompile your extension module with extra path information. For example, on Linux you can do this:
$ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \
-Xlinker -rpath /home/beazley/projects/lib \
-o example.so
Alternatively, you can set the LD_LIBRARY_PATH environment variable to include the directory with your shared libraries. If setting LD_LIBRARY_PATH, be aware that setting this variable can introduce a noticeable performance impact on all other applications that you run. To set it only for Perl, you might want to do this instead:
$ env LD_LIBRARY_PATH=/home/beazley/projects/lib perl
Finally, you can use a command such as ldconfig (Linux) or crle (Solaris) to add additional search paths to the default system configuration (this requires root access and you will need to read the man pages).
Compilation of C++ extensions has traditionally been a tricky problem. Since the Perl interpreter is written in C, you need to take steps to make sure C++ is properly initialized and that modules are compiled correctly.
On most machines, C++ extension modules should be linked using the C++ compiler. For example:
$ swig -c++ -perl example.i $ g++ -fPIC -c example.cxx $ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE $ g++ -shared example.o example_wrap.o -o example.so
In addition to this, you may need to include additional library files to make it work. For example, if you are using the Sun C++ compiler on Solaris, you often need to add an extra library -lCrun like this:
$ swig -c++ -perl example.i $ CC -Kpic -c example.cxx $ CC -Kpic -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE $ CC -shared example.o example_wrap.o -o example.so -lCrun
Of course, the names of the extra libraries are completely non-portable---you will probably need to do some experimentation.
Another possible compile problem comes from recent versions of Perl (5.8.0) and the GNU tools. If you see errors having to do with _crypt_struct, that means _GNU_SOURCE is not defined and it needs to be. So you should compile the wrapper like:
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
-D_GNU_SOURCE is also included in the Perl ccflags, which can be found by running
$ perl -e 'use Config; print "$Config{ccflags}\n";'
So you could also compile the wrapper like
$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
`perl -MConfig -e 'print $Config{ccflags}'`
Sometimes people have suggested that it is necessary to relink the Perl interpreter using the C++ compiler to make C++ extension modules work. In the experience of this author, this has never actually appeared to be necessary on most platforms. Relinking the interpreter with C++ really only includes the special run-time libraries described above---as long as you link your extension modules with these libraries, it should not be necessary to rebuild Perl.
If you aren't entirely sure about the linking of a C++ extension, you might look at an existing C++ program. On many Unix machines, the ldd command will list library dependencies. This should give you some clues about what you might have to include when you link your extension module. For example, notice the first line of output here:
$ ldd swig
libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000)
libm.so.6 => /lib/libm.so.6 (0x4005b0