package YourPackage;
require XSLoader;
XSLoader::load(__PACKAGE__, $VERSION);
For a more complicated interface, see DynaLoader. Many (most) features of "DynaLoader" are not implemented in "XSLoader", like for example the "dl_load_flags", not honored by "XSLoader".
package YourPackage;
require DynaLoader;
our @ISA = qw( OnePackage OtherPackage DynaLoader );
our $VERSION = '0.01';
__PACKAGE__->bootstrap($VERSION);
Change this to
package YourPackage;
use XSLoader;
our @ISA = qw( OnePackage OtherPackage );
our $VERSION = '0.01';
XSLoader::load(__PACKAGE__, $VERSION);
In other words: replace "require DynaLoader" by "use XSLoader", remove "DynaLoader" from @ISA, change "bootstrap" by "XSLoader::load". Do not forget to quote the name of your package on the "XSLoader::load" line, and add comma (",") before the arguments ($VERSION above).
Of course, if @ISA contained only "DynaLoader", there is no need to have the @ISA assignment at all; moreover, if instead of "our" one uses the more backward-compatible
use vars qw($VERSION @ISA);
one can remove this reference to @ISA together with the @ISA assignment.
If no $VERSION was specified on the "bootstrap" line, the last line becomes
XSLoader::load(__PACKAGE__);
in which case it can be further simplified to
XSLoader::load();
as "load" will use "caller" to determine the package.
package YourPackage;
our @ISA = qw( OnePackage OtherPackage );
our $VERSION = '0.01';
eval {
require XSLoader;
XSLoader::load(__PACKAGE__, $VERSION);
1;
} or do {
require DynaLoader;
push @ISA, 'DynaLoader';
__PACKAGE__->bootstrap($VERSION);
};
The parentheses about "XSLoader::load()" arguments are needed since we replaced "use XSLoader" by "require", so the compiler does not know that a function "XSLoader::load()" is present.
This boilerplate uses the low-overhead "XSLoader" if present; if used with an antique Perl which has no "XSLoader", it falls back to using "DynaLoader".
A sufficiently complicated module using XS would have both Perl code (defined in YourPackage.pm) and XS code (defined in YourPackage.xs). If this Perl code makes calls into this XS code, and/or this XS code makes calls to the Perl code, one should be careful with the order of initialization.
The call to "XSLoader::load()" (or "bootstrap()") calls the module's bootstrap code. For modules build by xsubpp (nearly all modules) this has three side effects:
Consequently, if the code in the .pm file makes calls to these XSUBs, it is convenient to have XSUBs installed before the Perl code is defined; for example, this makes prototypes for XSUBs visible to this Perl code. Alternatively, if the "BOOT:" section makes calls to Perl functions (or uses Perl variables) defined in the .pm file, they must be defined prior to the call to "XSLoader::load()" (or "bootstrap()").
The first situation being much more frequent, it makes sense to rewrite the boilerplate as
package YourPackage;
use XSLoader;
our ($VERSION, @ISA);
BEGIN {
@ISA = qw( OnePackage OtherPackage );
$VERSION = '0.01';
# Put Perl code used in the BOOT: section here
XSLoader::load(__PACKAGE__, $VERSION);
}
# Put Perl code making calls into XSUBs here
package YourPackage;
use XSLoader;
our ($VERSION, @ISA);
BEGIN {
@ISA = qw( OnePackage OtherPackage );
$VERSION = '0.01';
XSLoader::load(__PACKAGE__, $VERSION);
}
# Put Perl code used in onBOOT() function here; calls to XSUBs are
# prototype-checked.
onBOOT;
# Put Perl initialization code assuming that XS is initialized here
In particular, this is applicable to the structure of @INC used for testing not-yet-installed extensions. This means that running uninstalled extensions may have much more overhead than running the same extensions after "make install".
CPAN version is currently maintained by Sebastien Aperghis-Tramoni <sebastien@aperghis.net>.
Previous maintainer was Michael G Schwern <schwern@pobox.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.