1 | # Generated from XSLoader.pm.PL (resolved %Config::Config value)
|
---|
2 |
|
---|
3 | package XSLoader;
|
---|
4 |
|
---|
5 | $VERSION = "0.06";
|
---|
6 |
|
---|
7 | #use strict;
|
---|
8 |
|
---|
9 | # enable debug/trace messages from DynaLoader perl code
|
---|
10 | # $dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
|
---|
11 |
|
---|
12 | my $dl_dlext = 'dll';
|
---|
13 |
|
---|
14 | package DynaLoader;
|
---|
15 |
|
---|
16 | # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
|
---|
17 | # NOTE: All dl_*.xs (including dl_none.xs) define a dl_error() XSUB
|
---|
18 | boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
|
---|
19 | !defined(&dl_error);
|
---|
20 | package XSLoader;
|
---|
21 |
|
---|
22 | sub load {
|
---|
23 | package DynaLoader;
|
---|
24 |
|
---|
25 | die q{XSLoader::load('Your::Module', $Your::Module::VERSION)} unless @_;
|
---|
26 |
|
---|
27 | my($module) = $_[0];
|
---|
28 |
|
---|
29 | # work with static linking too
|
---|
30 | my $b = "$module\::bootstrap";
|
---|
31 | goto &$b if defined &$b;
|
---|
32 |
|
---|
33 | goto retry unless $module and defined &dl_load_file;
|
---|
34 |
|
---|
35 | my @modparts = split(/::/,$module);
|
---|
36 | my $modfname = $modparts[-1];
|
---|
37 |
|
---|
38 | my $modpname = join('/',@modparts);
|
---|
39 | my $modlibname = (caller())[1];
|
---|
40 | my $c = @modparts;
|
---|
41 | $modlibname =~ s,[\\/][^\\/]+$,, while $c--; # Q&D basename
|
---|
42 | my $file = "$modlibname/auto/$modpname/$modfname.$dl_dlext";
|
---|
43 |
|
---|
44 | # print STDERR "XSLoader::load for $module ($file)\n" if $dl_debug;
|
---|
45 |
|
---|
46 | my $bs = $file;
|
---|
47 | $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library
|
---|
48 |
|
---|
49 | goto retry if not -f $file or -s $bs;
|
---|
50 |
|
---|
51 | my $bootname = "boot_$module";
|
---|
52 | $bootname =~ s/\W/_/g;
|
---|
53 | @DynaLoader::dl_require_symbols = ($bootname);
|
---|
54 |
|
---|
55 | my $boot_symbol_ref;
|
---|
56 |
|
---|
57 | if ($^O eq 'darwin') {
|
---|
58 | if ($boot_symbol_ref = dl_find_symbol(0, $bootname)) {
|
---|
59 | goto boot; #extension library has already been loaded, e.g. darwin
|
---|
60 | }
|
---|
61 | }
|
---|
62 |
|
---|
63 | # Many dynamic extension loading problems will appear to come from
|
---|
64 | # this section of code: XYZ failed at line 123 of DynaLoader.pm.
|
---|
65 | # Often these errors are actually occurring in the initialisation
|
---|
66 | # C code of the extension XS file. Perl reports the error as being
|
---|
67 | # in this perl code simply because this was the last perl code
|
---|
68 | # it executed.
|
---|
69 |
|
---|
70 | my $libref = dl_load_file($file, 0) or do {
|
---|
71 | require Carp;
|
---|
72 | Carp::croak("Can't load '$file' for module $module: " . dl_error());
|
---|
73 | };
|
---|
74 | push(@DynaLoader::dl_librefs,$libref); # record loaded object
|
---|
75 |
|
---|
76 | my @unresolved = dl_undef_symbols();
|
---|
77 | if (@unresolved) {
|
---|
78 | require Carp;
|
---|
79 | Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
|
---|
80 | }
|
---|
81 |
|
---|
82 | $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
|
---|
83 | require Carp;
|
---|
84 | Carp::croak("Can't find '$bootname' symbol in $file\n");
|
---|
85 | };
|
---|
86 |
|
---|
87 | push(@DynaLoader::dl_modules, $module); # record loaded module
|
---|
88 |
|
---|
89 | boot:
|
---|
90 | my $xs = dl_install_xsub("${module}::bootstrap", $boot_symbol_ref, $file);
|
---|
91 |
|
---|
92 | # See comment block above
|
---|
93 | push(@DynaLoader::dl_shared_objects, $file); # record files loaded
|
---|
94 | return &$xs(@_);
|
---|
95 |
|
---|
96 | retry:
|
---|
97 | my $bootstrap_inherit = DynaLoader->can('bootstrap_inherit') ||
|
---|
98 | XSLoader->can('bootstrap_inherit');
|
---|
99 | goto &$bootstrap_inherit;
|
---|
100 | }
|
---|
101 |
|
---|
102 | # Versions of DynaLoader prior to 5.6.0 don't have this function.
|
---|
103 | sub bootstrap_inherit {
|
---|
104 | package DynaLoader;
|
---|
105 |
|
---|
106 | my $module = $_[0];
|
---|
107 | local *DynaLoader::isa = *{"$module\::ISA"};
|
---|
108 | local @DynaLoader::isa = (@DynaLoader::isa, 'DynaLoader');
|
---|
109 | # Cannot goto due to delocalization. Will report errors on a wrong line?
|
---|
110 | require DynaLoader;
|
---|
111 | DynaLoader::bootstrap(@_);
|
---|
112 | }
|
---|
113 |
|
---|
114 | 1;
|
---|
115 |
|
---|
116 |
|
---|
117 | __END__
|
---|
118 |
|
---|
119 | =head1 NAME
|
---|
120 |
|
---|
121 | XSLoader - Dynamically load C libraries into Perl code
|
---|
122 |
|
---|
123 | =head1 VERSION
|
---|
124 |
|
---|
125 | Version 0.06
|
---|
126 |
|
---|
127 | =head1 SYNOPSIS
|
---|
128 |
|
---|
129 | package YourPackage;
|
---|
130 | use XSLoader;
|
---|
131 |
|
---|
132 | XSLoader::load 'YourPackage', $YourPackage::VERSION;
|
---|
133 |
|
---|
134 | =head1 DESCRIPTION
|
---|
135 |
|
---|
136 | This module defines a standard I<simplified> interface to the dynamic
|
---|
137 | linking mechanisms available on many platforms. Its primary purpose is
|
---|
138 | to implement cheap automatic dynamic loading of Perl modules.
|
---|
139 |
|
---|
140 | For a more complicated interface, see L<DynaLoader>. Many (most)
|
---|
141 | features of C<DynaLoader> are not implemented in C<XSLoader>, like for
|
---|
142 | example the C<dl_load_flags>, not honored by C<XSLoader>.
|
---|
143 |
|
---|
144 | =head2 Migration from C<DynaLoader>
|
---|
145 |
|
---|
146 | A typical module using L<DynaLoader|DynaLoader> starts like this:
|
---|
147 |
|
---|
148 | package YourPackage;
|
---|
149 | require DynaLoader;
|
---|
150 |
|
---|
151 | our @ISA = qw( OnePackage OtherPackage DynaLoader );
|
---|
152 | our $VERSION = '0.01';
|
---|
153 | bootstrap YourPackage $VERSION;
|
---|
154 |
|
---|
155 | Change this to
|
---|
156 |
|
---|
157 | package YourPackage;
|
---|
158 | use XSLoader;
|
---|
159 |
|
---|
160 | our @ISA = qw( OnePackage OtherPackage );
|
---|
161 | our $VERSION = '0.01';
|
---|
162 | XSLoader::load 'YourPackage', $VERSION;
|
---|
163 |
|
---|
164 | In other words: replace C<require DynaLoader> by C<use XSLoader>, remove
|
---|
165 | C<DynaLoader> from C<@ISA>, change C<bootstrap> by C<XSLoader::load>. Do not
|
---|
166 | forget to quote the name of your package on the C<XSLoader::load> line,
|
---|
167 | and add comma (C<,>) before the arguments (C<$VERSION> above).
|
---|
168 |
|
---|
169 | Of course, if C<@ISA> contained only C<DynaLoader>, there is no need to have
|
---|
170 | the C<@ISA> assignment at all; moreover, if instead of C<our> one uses the
|
---|
171 | more backward-compatible
|
---|
172 |
|
---|
173 | use vars qw($VERSION @ISA);
|
---|
174 |
|
---|
175 | one can remove this reference to C<@ISA> together with the C<@ISA> assignment.
|
---|
176 |
|
---|
177 | If no C<$VERSION> was specified on the C<bootstrap> line, the last line becomes
|
---|
178 |
|
---|
179 | XSLoader::load 'YourPackage';
|
---|
180 |
|
---|
181 | =head2 Backward compatible boilerplate
|
---|
182 |
|
---|
183 | If you want to have your cake and eat it too, you need a more complicated
|
---|
184 | boilerplate.
|
---|
185 |
|
---|
186 | package YourPackage;
|
---|
187 | use vars qw($VERSION @ISA);
|
---|
188 |
|
---|
189 | @ISA = qw( OnePackage OtherPackage );
|
---|
190 | $VERSION = '0.01';
|
---|
191 | eval {
|
---|
192 | require XSLoader;
|
---|
193 | XSLoader::load('YourPackage', $VERSION);
|
---|
194 | 1;
|
---|
195 | } or do {
|
---|
196 | require DynaLoader;
|
---|
197 | push @ISA, 'DynaLoader';
|
---|
198 | bootstrap YourPackage $VERSION;
|
---|
199 | };
|
---|
200 |
|
---|
201 | The parentheses about C<XSLoader::load()> arguments are needed since we replaced
|
---|
202 | C<use XSLoader> by C<require>, so the compiler does not know that a function
|
---|
203 | C<XSLoader::load()> is present.
|
---|
204 |
|
---|
205 | This boilerplate uses the low-overhead C<XSLoader> if present; if used with
|
---|
206 | an antic Perl which has no C<XSLoader>, it falls back to using C<DynaLoader>.
|
---|
207 |
|
---|
208 | =head1 Order of initialization: early load()
|
---|
209 |
|
---|
210 | I<Skip this section if the XSUB functions are supposed to be called from other
|
---|
211 | modules only; read it only if you call your XSUBs from the code in your module,
|
---|
212 | or have a C<BOOT:> section in your XS file (see L<perlxs/"The BOOT: Keyword">).
|
---|
213 | What is described here is equally applicable to the L<DynaLoader|DynaLoader>
|
---|
214 | interface.>
|
---|
215 |
|
---|
216 | A sufficiently complicated module using XS would have both Perl code (defined
|
---|
217 | in F<YourPackage.pm>) and XS code (defined in F<YourPackage.xs>). If this
|
---|
218 | Perl code makes calls into this XS code, and/or this XS code makes calls to
|
---|
219 | the Perl code, one should be careful with the order of initialization.
|
---|
220 |
|
---|
221 | The call to C<XSLoader::load()> (or C<bootstrap()>) has three side effects:
|
---|
222 |
|
---|
223 | =over
|
---|
224 |
|
---|
225 | =item *
|
---|
226 |
|
---|
227 | if C<$VERSION> was specified, a sanity check is done to ensure that the
|
---|
228 | versions of the F<.pm> and the (compiled) F<.xs> parts are compatible;
|
---|
229 |
|
---|
230 | =item *
|
---|
231 |
|
---|
232 | the XSUBs are made accessible from Perl;
|
---|
233 |
|
---|
234 | =item *
|
---|
235 |
|
---|
236 | if a C<BOOT:> section was present in the F<.xs> file, the code there is called.
|
---|
237 |
|
---|
238 | =back
|
---|
239 |
|
---|
240 | Consequently, if the code in the F<.pm> file makes calls to these XSUBs, it is
|
---|
241 | convenient to have XSUBs installed before the Perl code is defined; for
|
---|
242 | example, this makes prototypes for XSUBs visible to this Perl code.
|
---|
243 | Alternatively, if the C<BOOT:> section makes calls to Perl functions (or
|
---|
244 | uses Perl variables) defined in the F<.pm> file, they must be defined prior to
|
---|
245 | the call to C<XSLoader::load()> (or C<bootstrap()>).
|
---|
246 |
|
---|
247 | The first situation being much more frequent, it makes sense to rewrite the
|
---|
248 | boilerplate as
|
---|
249 |
|
---|
250 | package YourPackage;
|
---|
251 | use XSLoader;
|
---|
252 | use vars qw($VERSION @ISA);
|
---|
253 |
|
---|
254 | BEGIN {
|
---|
255 | @ISA = qw( OnePackage OtherPackage );
|
---|
256 | $VERSION = '0.01';
|
---|
257 |
|
---|
258 | # Put Perl code used in the BOOT: section here
|
---|
259 |
|
---|
260 | XSLoader::load 'YourPackage', $VERSION;
|
---|
261 | }
|
---|
262 |
|
---|
263 | # Put Perl code making calls into XSUBs here
|
---|
264 |
|
---|
265 | =head2 The most hairy case
|
---|
266 |
|
---|
267 | If the interdependence of your C<BOOT:> section and Perl code is
|
---|
268 | more complicated than this (e.g., the C<BOOT:> section makes calls to Perl
|
---|
269 | functions which make calls to XSUBs with prototypes), get rid of the C<BOOT:>
|
---|
270 | section altogether. Replace it with a function C<onBOOT()>, and call it like
|
---|
271 | this:
|
---|
272 |
|
---|
273 | package YourPackage;
|
---|
274 | use XSLoader;
|
---|
275 | use vars qw($VERSION @ISA);
|
---|
276 |
|
---|
277 | BEGIN {
|
---|
278 | @ISA = qw( OnePackage OtherPackage );
|
---|
279 | $VERSION = '0.01';
|
---|
280 | XSLoader::load 'YourPackage', $VERSION;
|
---|
281 | }
|
---|
282 |
|
---|
283 | # Put Perl code used in onBOOT() function here; calls to XSUBs are
|
---|
284 | # prototype-checked.
|
---|
285 |
|
---|
286 | onBOOT;
|
---|
287 |
|
---|
288 | # Put Perl initialization code assuming that XS is initialized here
|
---|
289 |
|
---|
290 |
|
---|
291 | =head1 DIAGNOSTICS
|
---|
292 |
|
---|
293 | =over 4
|
---|
294 |
|
---|
295 | =item Can't find '%s' symbol in %s
|
---|
296 |
|
---|
297 | B<(F)> The bootstrap symbol could not be found in the extension module.
|
---|
298 |
|
---|
299 | =item Can't load '%s' for module %s: %s
|
---|
300 |
|
---|
301 | B<(F)> The loading or initialisation of the extension module failed.
|
---|
302 | The detailed error follows.
|
---|
303 |
|
---|
304 | =item Undefined symbols present after loading %s: %s
|
---|
305 |
|
---|
306 | B<(W)> As the message says, some symbols stay undefined although the
|
---|
307 | extension module was correctly loaded and initialised. The list of undefined
|
---|
308 | symbols follows.
|
---|
309 |
|
---|
310 | =item XSLoader::load('Your::Module', $Your::Module::VERSION)
|
---|
311 |
|
---|
312 | B<(F)> You tried to invoke C<load()> without any argument. You must supply
|
---|
313 | a module name, and optionally its version.
|
---|
314 |
|
---|
315 | =back
|
---|
316 |
|
---|
317 |
|
---|
318 | =head1 LIMITATIONS
|
---|
319 |
|
---|
320 | To reduce the overhead as much as possible, only one possible location
|
---|
321 | is checked to find the extension DLL (this location is where C<make install>
|
---|
322 | would put the DLL). If not found, the search for the DLL is transparently
|
---|
323 | delegated to C<DynaLoader>, which looks for the DLL along the C<@INC> list.
|
---|
324 |
|
---|
325 | In particular, this is applicable to the structure of C<@INC> used for testing
|
---|
326 | not-yet-installed extensions. This means that running uninstalled extensions
|
---|
327 | may have much more overhead than running the same extensions after
|
---|
328 | C<make install>.
|
---|
329 |
|
---|
330 |
|
---|
331 | =head1 BUGS
|
---|
332 |
|
---|
333 | Please report any bugs or feature requests via the perlbug(1) utility.
|
---|
334 |
|
---|
335 |
|
---|
336 | =head1 SEE ALSO
|
---|
337 |
|
---|
338 | L<DynaLoader>
|
---|
339 |
|
---|
340 |
|
---|
341 | =head1 AUTHORS
|
---|
342 |
|
---|
343 | Ilya Zakharevich originally extracted C<XSLoader> from C<DynaLoader>.
|
---|
344 |
|
---|
345 | CPAN version is currently maintained by SE<eacute>bastien Aperghis-Tramoni
|
---|
346 | E<lt>[email protected]<gt>
|
---|
347 |
|
---|
348 | Previous maintainer was Michael G Schwern <[email protected]>
|
---|
349 |
|
---|
350 |
|
---|
351 | =head1 COPYRIGHT
|
---|
352 |
|
---|
353 | This program is free software; you can redistribute it and/or modify
|
---|
354 | it under the same terms as Perl itself.
|
---|
355 |
|
---|
356 | =cut
|
---|