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