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
1 use strict;
2 use Config;
3
4 1 while unlink "XSLoader.pm";
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
11 $VERSION = "0.11";
12
13 #use strict;
14
15 # enable debug/trace messages from DynaLoader perl code
16 # $dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
17
18 package DynaLoader;
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
22 boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
23                                 !defined(&dl_error);
24 package XSLoader;
25
26 sub load {
27     package DynaLoader;
28
29     die q{XSLoader::load('Your::Module', $Your::Module::VERSION)} unless @_;
30
31     my($module) = $_[0];
32
33     # work with static linking too
34     my $boots = "$module\::bootstrap";
35     goto &$boots if defined &$boots;
36
37     goto retry unless $module and defined &dl_load_file;
38
39     my @modparts = split(/::/,$module);
40     my $modfname = $modparts[-1];
41
42 EOT
43
44 print 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
50 EOT
51
52 print 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
57 EOT
58
59 print OUT <<'EOT';
60     my $modpname = join('/',@modparts);
61     my $modlibname = (caller())[1];
62     my $c = @modparts;
63     $modlibname =~ s,[\\/][^\\/]+$,, while $c--;        # Q&D basename
64 EOT
65
66 my $dl_dlext = quotemeta($Config::Config{'dlext'});
67
68 print OUT <<"EOT";
69     my \$file = "\$modlibname/auto/\$modpname/\$modfname.$dl_dlext";
70 EOT
71
72 print OUT <<'EOT';
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
79     if (-s $bs) { # only read file if it's not empty
80 #       print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug;
81         eval { do $bs; };
82         warn "$bs: $@\n" if $@;
83     }
84
85     goto retry if not -f $file or -s $bs;
86
87     my $bootname = "boot_$module";
88     $bootname =~ s/\W/_/g;
89     @DynaLoader::dl_require_symbols = ($bootname);
90
91     my $boot_symbol_ref;
92
93 EOT
94
95     if ($^O eq 'darwin') {
96 print OUT <<'EOT';
97         if ($boot_symbol_ref = dl_find_symbol(0, $bootname)) {
98             goto boot; #extension library has already been loaded, e.g. darwin
99         }
100 EOT
101     }
102
103 print OUT <<'EOT';
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 { 
112         require Carp;
113         Carp::croak("Can't load '$file' for module $module: " . dl_error());
114     };
115     push(@DynaLoader::dl_librefs,$libref);  # record loaded object
116
117     my @unresolved = dl_undef_symbols();
118     if (@unresolved) {
119         require Carp;
120         Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
121     }
122
123     $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
124         require Carp;
125         Carp::croak("Can't find '$bootname' symbol in $file\n");
126     };
127
128     push(@DynaLoader::dl_modules, $module); # record loaded module
129
130   boot:
131     my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file);
132
133     # See comment block above
134     push(@DynaLoader::dl_shared_objects, $file); # record files loaded
135     return &$xs(@_);
136
137   retry:
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.
144 sub 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?
151     require DynaLoader;
152     DynaLoader::bootstrap(@_);
153 }
154
155 1;
156
157
158 __END__
159
160 =head1 NAME
161
162 XSLoader - Dynamically load C libraries into Perl code
163
164 =head1 VERSION
165
166 Version 0.10
167
168 =head1 SYNOPSIS
169
170     package YourPackage;
171     use XSLoader;
172
173     XSLoader::load 'YourPackage', $YourPackage::VERSION;
174
175 =head1 DESCRIPTION
176
177 This module defines a standard I<simplified> interface to the dynamic
178 linking mechanisms available on many platforms.  Its primary purpose is
179 to implement cheap automatic dynamic loading of Perl modules.
180
181 For a more complicated interface, see L<DynaLoader>.  Many (most)
182 features of C<DynaLoader> are not implemented in C<XSLoader>, like for
183 example the C<dl_load_flags>, not honored by C<XSLoader>.
184
185 =head2 Migration from C<DynaLoader>
186
187 A 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
196 Change 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
205 In other words: replace C<require DynaLoader> by C<use XSLoader>, remove
206 C<DynaLoader> from C<@ISA>, change C<bootstrap> by C<XSLoader::load>.  Do not
207 forget to quote the name of your package on the C<XSLoader::load> line,
208 and add comma (C<,>) before the arguments (C<$VERSION> above).
209
210 Of course, if C<@ISA> contained only C<DynaLoader>, there is no need to have
211 the C<@ISA> assignment at all; moreover, if instead of C<our> one uses the
212 more backward-compatible
213
214     use vars qw($VERSION @ISA);
215
216 one can remove this reference to C<@ISA> together with the C<@ISA> assignment.
217
218 If no C<$VERSION> was specified on the C<bootstrap> line, the last line becomes
219
220     XSLoader::load 'YourPackage';
221
222 =head2 Backward compatible boilerplate
223
224 If you want to have your cake and eat it too, you need a more complicated
225 boilerplate.
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
242 The parentheses about C<XSLoader::load()> arguments are needed since we replaced
243 C<use XSLoader> by C<require>, so the compiler does not know that a function
244 C<XSLoader::load()> is present.
245
246 This boilerplate uses the low-overhead C<XSLoader> if present; if used with
247 an antic Perl which has no C<XSLoader>, it falls back to using C<DynaLoader>.
248
249 =head1 Order of initialization: early load()
250
251 I<Skip this section if the XSUB functions are supposed to be called from other
252 modules only; read it only if you call your XSUBs from the code in your module,
253 or have a C<BOOT:> section in your XS file (see L<perlxs/"The BOOT: Keyword">).
254 What is described here is equally applicable to the L<DynaLoader|DynaLoader>
255 interface.>
256
257 A sufficiently complicated module using XS would have both Perl code (defined
258 in F<YourPackage.pm>) and XS code (defined in F<YourPackage.xs>).  If this
259 Perl code makes calls into this XS code, and/or this XS code makes calls to
260 the Perl code, one should be careful with the order of initialization.
261
262 The call to C<XSLoader::load()> (or C<bootstrap()>) has three side effects:
263
264 =over
265
266 =item *
267
268 if C<$VERSION> was specified, a sanity check is done to ensure that the
269 versions of the F<.pm> and the (compiled) F<.xs> parts are compatible;
270
271 =item *
272
273 the XSUBs are made accessible from Perl;
274
275 =item *
276
277 if a C<BOOT:> section was present in the F<.xs> file, the code there is called.
278
279 =back
280
281 Consequently, if the code in the F<.pm> file makes calls to these XSUBs, it is
282 convenient to have XSUBs installed before the Perl code is defined; for
283 example, this makes prototypes for XSUBs visible to this Perl code.
284 Alternatively, if the C<BOOT:> section makes calls to Perl functions (or
285 uses Perl variables) defined in the F<.pm> file, they must be defined prior to
286 the call to C<XSLoader::load()> (or C<bootstrap()>).
287
288 The first situation being much more frequent, it makes sense to rewrite the
289 boilerplate 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
308 If the interdependence of your C<BOOT:> section and Perl code is
309 more complicated than this (e.g., the C<BOOT:> section makes calls to Perl
310 functions which make calls to XSUBs with prototypes), get rid of the C<BOOT:>
311 section altogether.  Replace it with a function C<onBOOT()>, and call it like
312 this:
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
331
332 =head1 DIAGNOSTICS
333
334 =over
335
336 =item C<Can't find '%s' symbol in %s>
337
338 B<(F)> The bootstrap symbol could not be found in the extension module.
339
340 =item C<Can't load '%s' for module %s: %s>
341
342 B<(F)> The loading or initialisation of the extension module failed.
343 The detailed error follows.
344
345 =item C<Undefined symbols present after loading %s: %s>
346
347 B<(W)> As the message says, some symbols stay undefined although the
348 extension module was correctly loaded and initialised. The list of undefined
349 symbols follows.
350
351 =item C<XSLoader::load('Your::Module', $Your::Module::VERSION)>
352
353 B<(F)> You tried to invoke C<load()> without any argument. You must supply
354 a module name, and optionally its version.
355
356 =back
357
358
359 =head1 LIMITATIONS
360
361 To reduce the overhead as much as possible, only one possible location
362 is checked to find the extension DLL (this location is where C<make install>
363 would put the DLL).  If not found, the search for the DLL is transparently
364 delegated to C<DynaLoader>, which looks for the DLL along the C<@INC> list.
365
366 In particular, this is applicable to the structure of C<@INC> used for testing
367 not-yet-installed extensions.  This means that running uninstalled extensions
368 may have much more overhead than running the same extensions after
369 C<make install>.
370
371
372 =head1 BUGS
373
374 Please report any bugs or feature requests via the perlbug(1) utility.
375
376
377 =head1 SEE ALSO
378
379 L<DynaLoader>
380
381
382 =head1 AUTHORS
383
384 Ilya Zakharevich originally extracted C<XSLoader> from C<DynaLoader>.
385
386 CPAN version is currently maintained by SE<eacute>bastien Aperghis-Tramoni
387 E<lt>sebastien@aperghis.netE<gt>.
388
389 Previous maintainer was Michael G Schwern <schwern@pobox.com>.
390
391
392 =head1 COPYRIGHT & LICENSE
393
394 Copyright (C) 1990-2007 by Larry Wall and others.
395
396 This program is free software; you can redistribute it and/or modify
397 it under the same terms as Perl itself.
398
399 =cut
400 EOT
401
402 close OUT or die $!;