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