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