XSLoader(3pm)

1XSLoader(3pm)          Perl Programmers Reference Guide          XSLoader(3pm)
2
3
4

NAME

6       XSLoader - Dynamically load C libraries into Perl code
7

VERSION

9       Version 0.06
10

SYNOPSIS

12           package YourPackage;
13           use XSLoader;
14
15           XSLoader::load 'YourPackage', $YourPackage::VERSION;
16

DESCRIPTION

18       This module defines a standard simplified interface to the dynamic
19       linking mechanisms available on many platforms.  Its primary purpose is
20       to implement cheap automatic dynamic loading of Perl modules.
21
22       For a more complicated interface, see DynaLoader.  Many (most) features
23       of "DynaLoader" are not implemented in "XSLoader", like for example the
24       "dl_load_flags", not honored by "XSLoader".
25
26       Migration from "DynaLoader"
27
28       A typical module using DynaLoader starts like this:
29
30           package YourPackage;
31           require DynaLoader;
32
33           our @ISA = qw( OnePackage OtherPackage DynaLoader );
34           our $VERSION = '0.01';
35           bootstrap YourPackage $VERSION;
36
37       Change this to
38
39           package YourPackage;
40           use XSLoader;
41
42           our @ISA = qw( OnePackage OtherPackage );
43           our $VERSION = '0.01';
44           XSLoader::load 'YourPackage', $VERSION;
45
46       In other words: replace "require DynaLoader" by "use XSLoader", remove
47       "DynaLoader" from @ISA, change "bootstrap" by "XSLoader::load".  Do not
48       forget to quote the name of your package on the "XSLoader::load" line,
49       and add comma (",") before the arguments ($VERSION above).
50
51       Of course, if @ISA contained only "DynaLoader", there is no need to
52       have the @ISA assignment at all; moreover, if instead of "our" one uses
53       the more backward-compatible
54
55           use vars qw($VERSION @ISA);
56
57       one can remove this reference to @ISA together with the @ISA assign‐
58       ment.
59
60       If no $VERSION was specified on the "bootstrap" line, the last line
61       becomes
62
63           XSLoader::load 'YourPackage';
64
65       Backward compatible boilerplate
66
67       If you want to have your cake and eat it too, you need a more compli‐
68       cated boilerplate.
69
70           package YourPackage;
71           use vars qw($VERSION @ISA);
72
73           @ISA = qw( OnePackage OtherPackage );
74           $VERSION = '0.01';
75           eval {
76              require XSLoader;
77              XSLoader::load('YourPackage', $VERSION);
78              1;
79           } or do {
80              require DynaLoader;
81              push @ISA, 'DynaLoader';
82              bootstrap YourPackage $VERSION;
83           };
84
85       The parentheses about "XSLoader::load()" arguments are needed since we
86       replaced "use XSLoader" by "require", so the compiler does not know
87       that a function "XSLoader::load()" is present.
88
89       This boilerplate uses the low-overhead "XSLoader" if present; if used
90       with an antic Perl which has no "XSLoader", it falls back to using
91       "DynaLoader".
92

Order of initialization: early load()

94       Skip this section if the XSUB functions are supposed to be called from
95       other modules only; read it only if you call your XSUBs from the code
96       in your module, or have a "BOOT:" section in your XS file (see "The
97       BOOT: Keyword" in perlxs).  What is described here is equally applica‐
98       ble to the DynaLoader interface.
99
100       A sufficiently complicated module using XS would have both Perl code
101       (defined in YourPackage.pm) and XS code (defined in YourPackage.xs).
102       If this Perl code makes calls into this XS code, and/or this XS code
103       makes calls to the Perl code, one should be careful with the order of
104       initialization.
105
106       The call to "XSLoader::load()" (or "bootstrap()") has three side
107       effects:
108
109       ·   if $VERSION was specified, a sanity check is done to ensure that
110           the versions of the .pm and the (compiled) .xs parts are compati‐
111           ble;
112
113       ·   the XSUBs are made accessible from Perl;
114
115       ·   if a "BOOT:" section was present in the .xs file, the code there is
116           called.
117
118       Consequently, if the code in the .pm file makes calls to these XSUBs,
119       it is convenient to have XSUBs installed before the Perl code is
120       defined; for example, this makes prototypes for XSUBs visible to this
121       Perl code.  Alternatively, if the "BOOT:" section makes calls to Perl
122       functions (or uses Perl variables) defined in the .pm file, they must
123       be defined prior to the call to "XSLoader::load()" (or "bootstrap()").
124
125       The first situation being much more frequent, it makes sense to rewrite
126       the boilerplate as
127
128           package YourPackage;
129           use XSLoader;
130           use vars qw($VERSION @ISA);
131
132           BEGIN {
133              @ISA = qw( OnePackage OtherPackage );
134              $VERSION = '0.01';
135
136              # Put Perl code used in the BOOT: section here
137
138              XSLoader::load 'YourPackage', $VERSION;
139           }
140
141           # Put Perl code making calls into XSUBs here
142
143       The most hairy case
144
145       If the interdependence of your "BOOT:" section and Perl code is more
146       complicated than this (e.g., the "BOOT:" section makes calls to Perl
147       functions which make calls to XSUBs with prototypes), get rid of the
148       "BOOT:" section altogether.  Replace it with a function "onBOOT()", and
149       call it like this:
150
151           package YourPackage;
152           use XSLoader;
153           use vars qw($VERSION @ISA);
154
155           BEGIN {
156              @ISA = qw( OnePackage OtherPackage );
157              $VERSION = '0.01';
158              XSLoader::load 'YourPackage', $VERSION;
159           }
160
161           # Put Perl code used in onBOOT() function here; calls to XSUBs are
162           # prototype-checked.
163
164           onBOOT;
165
166           # Put Perl initialization code assuming that XS is initialized here
167

DIAGNOSTICS

169       Can't find '%s' symbol in %s
170           (F) The bootstrap symbol could not be found in the extension mod‐
171           ule.
172
173       Can't load '%s' for module %s: %s
174           (F) The loading or initialisation of the extension module failed.
175           The detailed error follows.
176
177       Undefined symbols present after loading %s: %s
178           (W) As the message says, some symbols stay undefined although the
179           extension module was correctly loaded and initialised. The list of
180           undefined symbols follows.
181
182       XSLoader::load('Your::Module', $Your::Module::VERSION)
183           (F) You tried to invoke "load()" without any argument. You must
184           supply a module name, and optionally its version.
185

LIMITATIONS

187       To reduce the overhead as much as possible, only one possible location
188       is checked to find the extension DLL (this location is where "make
189       install" would put the DLL).  If not found, the search for the DLL is
190       transparently delegated to "DynaLoader", which looks for the DLL along
191       the @INC list.
192
193       In particular, this is applicable to the structure of @INC used for
194       testing not-yet-installed extensions.  This means that running unin‐
195       stalled extensions may have much more overhead than running the same
196       extensions after "make install".
197

BUGS

199       Please report any bugs or feature requests via the perlbug(1) utility.
200

AUTHORS

205       Ilya Zakharevich originally extracted "XSLoader" from "DynaLoader".
206
207       CPAN version is currently maintained by Sebastien Aperghis-Tramoni
208       <sebastien@aperghis.net>
209
210       Previous maintainer was Michael G Schwern <schwern@pobox.com>
211

COPYRIGHT

213       This program is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215
216
217
218perl v5.8.8                       2001-09-21                     XSLoader(3pm)