Commit | Line | Data |
---|---|---|
920dae64 AT |
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 |