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