dist/XSLoader/XSLoader_pm.PL

   1 use strict;
   2 use Config;
   3 # We require DynaLoader to make sure that mod2fname is loaded
   4 eval { require DynaLoader };
   5
   6 1 while unlink "XSLoader.pm";
   7 open OUT, '>', 'XSLoader.pm' or die $!;
   8 print OUT <<'EOT';
   9 # Generated from XSLoader.pm.PL (resolved %Config::Config value)
  10 # This file is unique for every OS
  11
  12 package XSLoader;
  13
  14 $VERSION = "0.26";
  15
  16 #use strict;
  17
  18 package DynaLoader;
  19
  20 EOT
  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
  35 print OUT <<'EOT' if $] < 5.006;
  36
  37 # enable debug/trace messages from DynaLoader perl code
  38 $dl_debug = $ENV{PERL_DL_DEBUG} || 0 unless defined $dl_debug;
  39
  40 EOT
  41
  42 print OUT <<'EOT';
  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
  45 boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) &&
  46                                 !defined(&dl_error);
  47 package XSLoader;
  48
  49 sub load {
  50     package DynaLoader;
  51
  52     my ($caller, $modlibname) = caller();
  53     my $module = $caller;
  54
  55     if (@_) {
  56         $module = $_[0];
  57     } else {
  58         $_[0] = $module;
  59     }
  60
  61     # work with static linking too
  62     my $boots = "$module\::bootstrap";
  63     goto &$boots if defined &$boots;
  64
  65     goto \&XSLoader::bootstrap_inherit unless $module and defined &dl_load_file;
  66
  67     my @modparts = split(/::/,$module);
  68     my $modfname = $modparts[-1];
  69
  70 EOT
  71
  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.
  75 print OUT <<'EOT' if defined &DynaLoader::mod2fname || $Config{d_libname_unique};
  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.
  79     $modfname = &DynaLoader::mod2fname(\@modparts) if defined &DynaLoader::mod2fname;
  80
  81 EOT
  82
  83 print 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
  88 EOT
  89
  90 print OUT <<'EOT';
  91     my $modpname = join('/',@modparts);
  92     my $c = () = split(/::/,$caller,-1);
  93     $modlibname =~ s,[\\/][^\\/]+$,, while $c--;    # Q&D basename
  94 EOT
  95
  96 my $to_print = <<'EOT';
  97     # Does this look like a relative path?
  98     if ($modlibname !~ m{regexp}) {
  99 EOT
 100
 101 $to_print =~ s~regexp~
 102     $^O eq 'MSWin32' || $^O eq 'os2' || $^O eq 'cygwin' || $^O eq 'amigaos'
 103         ? '^(?:[A-Za-z]:)?[\\\/]' # Optional drive letter
 104         : '^/'
 105 ~e;
 106
 107 print OUT $to_print, <<'EOT';
 108         # Someone may have a #line directive that changes the file name, or
 109         # may be calling XSLoader::load from inside a string eval.  We cer-
 110         # tainly do not want to go loading some code that is not in @INC,
 111         # as it could be untrusted.
 112         #
 113         # We could just fall back to DynaLoader here, but then the rest of
 114         # this function would go untested in the perl core, since all @INC
 115         # paths are relative during testing.  That would be a time bomb
 116         # waiting to happen, since bugs could be introduced into the code.
 117         #
 118         # So look through @INC to see if $modlibname is in it.  A rela-
 119         # tive $modlibname is not a common occurrence, so this block is
 120         # not hot code.
 121         FOUND: {
 122             for (@INC) {
 123                 if ($_ eq $modlibname) {
 124                     last FOUND;
 125                 }
 126             }
 127             # Not found.  Fall back to DynaLoader.
 128             goto \&XSLoader::bootstrap_inherit;
 129         }
 130     }
 131 EOT
 132
 133 my $dl_dlext = quotemeta($Config::Config{'dlext'});
 134
 135 print OUT <<"EOT";
 136     my \$file = "\$modlibname/auto/\$modpname/\$modfname.$dl_dlext";
 137 EOT
 138
 139 print OUT <<'EOT';
 140
 141 #   print STDERR "XSLoader::load for $module ($file)\n" if $dl_debug;
 142
 143     my $bs = $file;
 144     $bs =~ s/(\.\w+)?(;\d*)?$/\.bs/; # look for .bs 'beside' the library
 145
 146     if (-s $bs) { # only read file if it's not empty
 147 #       print STDERR "BS: $bs ($^O, $dlsrc)\n" if $dl_debug;
 148         eval { do $bs; };
 149         warn "$bs: $@\n" if $@;
 150         goto \&XSLoader::bootstrap_inherit;
 151     }
 152
 153     goto \&XSLoader::bootstrap_inherit if not -f $file;
 154
 155     my $bootname = "boot_$module";
 156     $bootname =~ s/\W/_/g;
 157     @DynaLoader::dl_require_symbols = ($bootname);
 158
 159     my $boot_symbol_ref;
 160
 161 EOT
 162
 163     if ($^O eq 'darwin') {
 164       my $extra_arg = ', 1 ' if $DynaLoader::VERSION ge '1.37';
 165 print OUT <<"EOT";
 166     if (\$boot_symbol_ref = dl_find_symbol( 0, \$bootname $extra_arg)) {
 167         goto boot; #extension library has already been loaded, e.g. darwin
 168     }
 169 EOT
 170     }
 171
 172 print OUT <<'EOT';
 173     # Many dynamic extension loading problems will appear to come from
 174     # this section of code: XYZ failed at line 123 of DynaLoader.pm.
 175     # Often these errors are actually occurring in the initialisation
 176     # C code of the extension XS file. Perl reports the error as being
 177     # in this perl code simply because this was the last perl code
 178     # it executed.
 179
 180     my $libref = dl_load_file($file, 0) or do {
 181         require Carp;
 182         Carp::croak("Can't load '$file' for module $module: " . dl_error());
 183     };
 184     push(@DynaLoader::dl_librefs,$libref);  # record loaded object
 185
 186 EOT
 187 my $dlsrc = $Config{dlsrc};
 188 if ($dlsrc eq 'dl_freemint.xs' || $dlsrc eq 'dl_dld.xs') {
 189     print OUT <<'EOT';
 190     my @unresolved = dl_undef_symbols();
 191     if (@unresolved) {
 192         require Carp;
 193         Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
 194     }
 195
 196 EOT
 197 }
 198
 199 print OUT <<'EOT';
 200     $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
 201         require Carp;
 202         Carp::croak("Can't find '$bootname' symbol in $file\n");
 203     };
 204
 205     push(@DynaLoader::dl_modules, $module); # record loaded module
 206
 207   boot:
 208     my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file);
 209
 210     # See comment block above
 211     push(@DynaLoader::dl_shared_objects, $file); # record files loaded
 212     return &$xs(@_);
 213 }
 214 EOT
 215
 216 # Can't test with DynaLoader->can('bootstrap_inherit') when building in the
 217 # core, as XSLoader gets built before DynaLoader.
 218
 219 if ($] >= 5.006) {
 220     print OUT <<'EOT';
 221
 222 sub bootstrap_inherit {
 223     require DynaLoader;
 224     goto \&DynaLoader::bootstrap_inherit;
 225 }
 226
 227 EOT
 228 } else {
 229     print OUT <<'EOT';
 230
 231 sub bootstrap_inherit {
 232     # Versions of DynaLoader prior to 5.6.0 don't have bootstrap_inherit.
 233     package DynaLoader;
 234
 235     my $module = $_[0];
 236     local *DynaLoader::isa = *{"$module\::ISA"};
 237     local @DynaLoader::isa = (@DynaLoader::isa, 'DynaLoader');
 238     # Cannot goto due to delocalization.  Will report errors on a wrong line?
 239     require DynaLoader;
 240     DynaLoader::bootstrap(@_);
 241 }
 242
 243 EOT
 244 }
 245
 246 print OUT <<'EOT';
 247 1;
 248
 249
 250 __END__
 251
 252 =head1 NAME
 253
 254 XSLoader - Dynamically load C libraries into Perl code
 255
 256 =head1 VERSION
 257
 258 Version 0.24
 259
 260 =head1 SYNOPSIS
 261
 262     package YourPackage;
 263     require XSLoader;
 264
 265     XSLoader::load();
 266
 267 =head1 DESCRIPTION
 268
 269 This module defines a standard I<simplified> interface to the dynamic
 270 linking mechanisms available on many platforms.  Its primary purpose is
 271 to implement cheap automatic dynamic loading of Perl modules.
 272
 273 For a more complicated interface, see L<DynaLoader>.  Many (most)
 274 features of C<DynaLoader> are not implemented in C<XSLoader>, like for
 275 example the C<dl_load_flags>, not honored by C<XSLoader>.
 276
 277 =head2 Migration from C<DynaLoader>
 278
 279 A typical module using L<DynaLoader|DynaLoader> starts like this:
 280
 281     package YourPackage;
 282     require DynaLoader;
 283
 284     our @ISA = qw( OnePackage OtherPackage DynaLoader );
 285     our $VERSION = '0.01';
 286     bootstrap YourPackage $VERSION;
 287
 288 Change this to
 289
 290     package YourPackage;
 291     use XSLoader;
 292
 293     our @ISA = qw( OnePackage OtherPackage );
 294     our $VERSION = '0.01';
 295     XSLoader::load 'YourPackage', $VERSION;
 296
 297 In other words: replace C<require DynaLoader> by C<use XSLoader>, remove
 298 C<DynaLoader> from C<@ISA>, change C<bootstrap> by C<XSLoader::load>.  Do not
 299 forget to quote the name of your package on the C<XSLoader::load> line,
 300 and add comma (C<,>) before the arguments (C<$VERSION> above).
 301
 302 Of course, if C<@ISA> contained only C<DynaLoader>, there is no need to have
 303 the C<@ISA> assignment at all; moreover, if instead of C<our> one uses the
 304 more backward-compatible
 305
 306     use vars qw($VERSION @ISA);
 307
 308 one can remove this reference to C<@ISA> together with the C<@ISA> assignment.
 309
 310 If no C<$VERSION> was specified on the C<bootstrap> line, the last line becomes
 311
 312     XSLoader::load 'YourPackage';
 313
 314 If the call to C<load> is from C<YourPackage>, then that can be further
 315 simplified to
 316
 317     XSLoader::load();
 318
 319 as C<load> will use C<caller> to determine the package.
 320
 321 =head2 Backward compatible boilerplate
 322
 323 If you want to have your cake and eat it too, you need a more complicated
 324 boilerplate.
 325
 326     package YourPackage;
 327     use vars qw($VERSION @ISA);
 328
 329     @ISA = qw( OnePackage OtherPackage );
 330     $VERSION = '0.01';
 331     eval {
 332        require XSLoader;
 333        XSLoader::load('YourPackage', $VERSION);
 334        1;
 335     } or do {
 336        require DynaLoader;
 337        push @ISA, 'DynaLoader';
 338        bootstrap YourPackage $VERSION;
 339     };
 340
 341 The parentheses about C<XSLoader::load()> arguments are needed since we replaced
 342 C<use XSLoader> by C<require>, so the compiler does not know that a function
 343 C<XSLoader::load()> is present.
 344
 345 This boilerplate uses the low-overhead C<XSLoader> if present; if used with
 346 an antique Perl which has no C<XSLoader>, it falls back to using C<DynaLoader>.
 347
 348 =head1 Order of initialization: early load()
 349
 350 I<Skip this section if the XSUB functions are supposed to be called from other
 351 modules only; read it only if you call your XSUBs from the code in your module,
 352 or have a C<BOOT:> section in your XS file (see L<perlxs/"The BOOT: Keyword">).
 353 What is described here is equally applicable to the L<DynaLoader|DynaLoader>
 354 interface.>
 355
 356 A sufficiently complicated module using XS would have both Perl code (defined
 357 in F<YourPackage.pm>) and XS code (defined in F<YourPackage.xs>).  If this
 358 Perl code makes calls into this XS code, and/or this XS code makes calls to
 359 the Perl code, one should be careful with the order of initialization.
 360
 361 The call to C<XSLoader::load()> (or C<bootstrap()>) calls the module's
 362 bootstrap code. For modules build by F<xsubpp> (nearly all modules) this
 363 has three side effects:
 364
 365 =over
 366
 367 =item *
 368
 369 A sanity check is done to ensure that the versions of the F<.pm> and the
 370 (compiled) F<.xs> parts are compatible. If C<$VERSION> was specified, this
 371 is used for the check. If not specified, it defaults to
 372 C<$XS_VERSION // $VERSION> (in the module's namespace)
 373
 374 =item *
 375
 376 the XSUBs are made accessible from Perl
 377
 378 =item *
 379
 380 if a C<BOOT:> section was present in the F<.xs> file, the code there is called.
 381
 382 =back
 383
 384 Consequently, if the code in the F<.pm> file makes calls to these XSUBs, it is
 385 convenient to have XSUBs installed before the Perl code is defined; for
 386 example, this makes prototypes for XSUBs visible to this Perl code.
 387 Alternatively, if the C<BOOT:> section makes calls to Perl functions (or
 388 uses Perl variables) defined in the F<.pm> file, they must be defined prior to
 389 the call to C<XSLoader::load()> (or C<bootstrap()>).
 390
 391 The first situation being much more frequent, it makes sense to rewrite the
 392 boilerplate as
 393
 394     package YourPackage;
 395     use XSLoader;
 396     use vars qw($VERSION @ISA);
 397
 398     BEGIN {
 399        @ISA = qw( OnePackage OtherPackage );
 400        $VERSION = '0.01';
 401
 402        # Put Perl code used in the BOOT: section here
 403
 404        XSLoader::load 'YourPackage', $VERSION;
 405     }
 406
 407     # Put Perl code making calls into XSUBs here
 408
 409 =head2 The most hairy case
 410
 411 If the interdependence of your C<BOOT:> section and Perl code is
 412 more complicated than this (e.g., the C<BOOT:> section makes calls to Perl
 413 functions which make calls to XSUBs with prototypes), get rid of the C<BOOT:>
 414 section altogether.  Replace it with a function C<onBOOT()>, and call it like
 415 this:
 416
 417     package YourPackage;
 418     use XSLoader;
 419     use vars qw($VERSION @ISA);
 420
 421     BEGIN {
 422        @ISA = qw( OnePackage OtherPackage );
 423        $VERSION = '0.01';
 424        XSLoader::load 'YourPackage', $VERSION;
 425     }
 426
 427     # Put Perl code used in onBOOT() function here; calls to XSUBs are
 428     # prototype-checked.
 429
 430     onBOOT;
 431
 432     # Put Perl initialization code assuming that XS is initialized here
 433
 434
 435 =head1 DIAGNOSTICS
 436
 437 =over
 438
 439 =item C<Can't find '%s' symbol in %s>
 440
 441 B<(F)> The bootstrap symbol could not be found in the extension module.
 442
 443 =item C<Can't load '%s' for module %s: %s>
 444
 445 B<(F)> The loading or initialisation of the extension module failed.
 446 The detailed error follows.
 447
 448 =item C<Undefined symbols present after loading %s: %s>
 449
 450 B<(W)> As the message says, some symbols stay undefined although the
 451 extension module was correctly loaded and initialised. The list of undefined
 452 symbols follows.
 453
 454 =back
 455
 456 =head1 LIMITATIONS
 457
 458 To reduce the overhead as much as possible, only one possible location
 459 is checked to find the extension DLL (this location is where C<make install>
 460 would put the DLL).  If not found, the search for the DLL is transparently
 461 delegated to C<DynaLoader>, which looks for the DLL along the C<@INC> list.
 462
 463 In particular, this is applicable to the structure of C<@INC> used for testing
 464 not-yet-installed extensions.  This means that running uninstalled extensions
 465 may have much more overhead than running the same extensions after
 466 C<make install>.
 467
 468
 469 =head1 KNOWN BUGS
 470
 471 The new simpler way to call C<XSLoader::load()> with no arguments at all
 472 does not work on Perl 5.8.4 and 5.8.5.
 473
 474
 475 =head1 BUGS
 476
 477 Please report any bugs or feature requests via the perlbug(1) utility.
 478
 479
 480 =head1 SEE ALSO
 481
 482 L<DynaLoader>
 483
 484
 485 =head1 AUTHORS
 486
 487 Ilya Zakharevich originally extracted C<XSLoader> from C<DynaLoader>.
 488
 489 CPAN version is currently maintained by SE<eacute>bastien Aperghis-Tramoni
 490 E<lt>sebastien@aperghis.netE<gt>.
 491
 492 Previous maintainer was Michael G Schwern <schwern@pobox.com>.
 493
 494
 495 =head1 COPYRIGHT & LICENSE
 496
 497 Copyright (C) 1990-2011 by Larry Wall and others.
 498
 499 This program is free software; you can redistribute it and/or modify
 500 it under the same terms as Perl itself.
 501
 502 =cut
 503 EOT
 504
 505 close OUT or die $!;