1XSLoader(3pm) Perl Programmers Reference Guide XSLoader(3pm)
2
6 XSLoader - Dynamically load C libraries into Perl code
7
9 Version 0.10
10
12 package YourPackage;
13 use XSLoader;
14 XSLoader::load 'YourPackage', $YourPackage::VERSION;
16
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 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 Migration from "DynaLoader"
27 A typical module using DynaLoader starts like this:
28 package YourPackage;
30 require DynaLoader;
31 our @ISA = qw( OnePackage OtherPackage DynaLoader );
33 our $VERSION = '0.01';
34 bootstrap YourPackage $VERSION;
35 Change this to
37 package YourPackage;
39 use XSLoader;
40 our @ISA = qw( OnePackage OtherPackage );
42 our $VERSION = '0.01';
43 XSLoader::load 'YourPackage', $VERSION;
44 In other words: replace "require DynaLoader" by "use XSLoader", remove
46 "DynaLoader" from @ISA, change "bootstrap" by "XSLoader::load". Do not
47 forget to quote the name of your package on the "XSLoader::load" line,
48 and add comma (",") before the arguments ($VERSION above).
49 Of course, if @ISA contained only "DynaLoader", there is no need to
51 have the @ISA assignment at all; moreover, if instead of "our" one uses
52 the more backward-compatible
53 use vars qw($VERSION @ISA);
55 one can remove this reference to @ISA together with the @ISA
57 assignment.
58 If no $VERSION was specified on the "bootstrap" line, the last line
60 becomes
61 XSLoader::load 'YourPackage';
63 Backward compatible boilerplate
65 If you want to have your cake and eat it too, you need a more
66 complicated boilerplate.
67 package YourPackage;
69 use vars qw($VERSION @ISA);
70 @ISA = qw( OnePackage OtherPackage );
72 $VERSION = '0.01';
73 eval {
74 require XSLoader;
75 XSLoader::load('YourPackage', $VERSION);
76 1;
77 } or do {
78 require DynaLoader;
79 push @ISA, 'DynaLoader';
80 bootstrap YourPackage $VERSION;
81 };
82 The parentheses about "XSLoader::load()" arguments are needed since we
84 replaced "use XSLoader" by "require", so the compiler does not know
85 that a function "XSLoader::load()" is present.
86 This boilerplate uses the low-overhead "XSLoader" if present; if used
88 with an antic Perl which has no "XSLoader", it falls back to using
89 "DynaLoader".
90
92 Skip this section if the XSUB functions are supposed to be called from
93 other modules only; read it only if you call your XSUBs from the code
94 in your module, or have a "BOOT:" section in your XS file (see "The
95 BOOT: Keyword" in perlxs). What is described here is equally
96 applicable to the DynaLoader interface.
97 A sufficiently complicated module using XS would have both Perl code
99 (defined in YourPackage.pm) and XS code (defined in YourPackage.xs).
100 If this Perl code makes calls into this XS code, and/or this XS code
101 makes calls to the Perl code, one should be careful with the order of
102 initialization.
103 The call to "XSLoader::load()" (or "bootstrap()") has three side
105 effects:
106 · if $VERSION was specified, a sanity check is done to ensure that
108 the versions of the .pm and the (compiled) .xs parts are
109 compatible;
110 · the XSUBs are made accessible from Perl;
112 · if a "BOOT:" section was present in the .xs file, the code there is
114 called.
115 Consequently, if the code in the .pm file makes calls to these XSUBs,
117 it is convenient to have XSUBs installed before the Perl code is
118 defined; for example, this makes prototypes for XSUBs visible to this
119 Perl code. Alternatively, if the "BOOT:" section makes calls to Perl
120 functions (or uses Perl variables) defined in the .pm file, they must
121 be defined prior to the call to "XSLoader::load()" (or "bootstrap()").
122 The first situation being much more frequent, it makes sense to rewrite
124 the boilerplate as
125 package YourPackage;
127 use XSLoader;
128 use vars qw($VERSION @ISA);
129 BEGIN {
131 @ISA = qw( OnePackage OtherPackage );
132 $VERSION = '0.01';
133 # Put Perl code used in the BOOT: section here
135 XSLoader::load 'YourPackage', $VERSION;
137 }
138 # Put Perl code making calls into XSUBs here
140 The most hairy case
142 If the interdependence of your "BOOT:" section and Perl code is more
143 complicated than this (e.g., the "BOOT:" section makes calls to Perl
144 functions which make calls to XSUBs with prototypes), get rid of the
145 "BOOT:" section altogether. Replace it with a function "onBOOT()", and
146 call it like this:
147 package YourPackage;
149 use XSLoader;
150 use vars qw($VERSION @ISA);
151 BEGIN {
153 @ISA = qw( OnePackage OtherPackage );
154 $VERSION = '0.01';
155 XSLoader::load 'YourPackage', $VERSION;
156 }
157 # Put Perl code used in onBOOT() function here; calls to XSUBs are
159 # prototype-checked.
160 onBOOT;
162 # Put Perl initialization code assuming that XS is initialized here
164
166 "Can't find '%s' symbol in %s"
167 (F) The bootstrap symbol could not be found in the extension
168 module.
169 "Can't load '%s' for module %s: %s"
171 (F) The loading or initialisation of the extension module failed.
172 The detailed error follows.
173 "Undefined symbols present after loading %s: %s"
175 (W) As the message says, some symbols stay undefined although the
176 extension module was correctly loaded and initialised. The list of
177 undefined symbols follows.
178 "XSLoader::load('Your::Module', $Your::Module::VERSION)"
180 (F) You tried to invoke "load()" without any argument. You must
181 supply a module name, and optionally its version.
182
184 To reduce the overhead as much as possible, only one possible location
185 is checked to find the extension DLL (this location is where "make
186 install" would put the DLL). If not found, the search for the DLL is
187 transparently delegated to "DynaLoader", which looks for the DLL along
188 the @INC list.
189 In particular, this is applicable to the structure of @INC used for
191 testing not-yet-installed extensions. This means that running
192 uninstalled extensions may have much more overhead than running the
193 same extensions after "make install".
194
196 Please report any bugs or feature requests via the perlbug(1) utility.
197
199 DynaLoader
200
202 Ilya Zakharevich originally extracted "XSLoader" from "DynaLoader".
203 CPAN version is currently maintained by Sebastien Aperghis-Tramoni
205 <sebastien@aperghis.net>.
206 Previous maintainer was Michael G Schwern <schwern@pobox.com>.
208
210 Copyright (C) 1990-2007 by Larry Wall and others.
211 This program is free software; you can redistribute it and/or modify it
213 under the same terms as Perl itself.
214perl v5.12.4 2011-11-04 XSLoader(3pm)