2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml">
5 <title>XSLoader - Dynamically load C libraries into Perl code
</title>
6 <meta http-equiv=
"content-type" content=
"text/html; charset=utf-8" />
7 <link rev=
"made" href=
"mailto:" />
10 <body style=
"background-color: white">
11 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
12 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
13 <big><strong><span class=
"block"> XSLoader - Dynamically load C libraries into Perl code
</span></strong></big>
17 <p><a name=
"__index__"></a></p>
22 <li><a href=
"#name">NAME
</a></li>
23 <li><a href=
"#version">VERSION
</a></li>
24 <li><a href=
"#synopsis">SYNOPSIS
</a></li>
25 <li><a href=
"#description">DESCRIPTION
</a></li>
28 <li><a href=
"#migration_from_dynaloader">Migration from
<code>DynaLoader
</code></a></li>
29 <li><a href=
"#backward_compatible_boilerplate">Backward compatible boilerplate
</a></li>
32 <li><a href=
"#order_of_initialization__early_load__">Order of initialization: early
<code>load()
</code></a></li>
35 <li><a href=
"#the_most_hairy_case">The most hairy case
</a></li>
38 <li><a href=
"#diagnostics">DIAGNOSTICS
</a></li>
39 <li><a href=
"#limitations">LIMITATIONS
</a></li>
40 <li><a href=
"#bugs">BUGS
</a></li>
41 <li><a href=
"#see_also">SEE ALSO
</a></li>
42 <li><a href=
"#authors">AUTHORS
</a></li>
43 <li><a href=
"#copyright">COPYRIGHT
</a></li>
50 <h1><a name=
"name">NAME
</a></h1>
51 <p>XSLoader - Dynamically load C libraries into Perl code
</p>
55 <h1><a name=
"version">VERSION
</a></h1>
60 <h1><a name=
"synopsis">SYNOPSIS
</a></h1>
65 XSLoader::load 'YourPackage', $YourPackage::VERSION;
</pre>
69 <h1><a name=
"description">DESCRIPTION
</a></h1>
70 <p>This module defines a standard
<em>simplified
</em> interface to the dynamic
71 linking mechanisms available on many platforms. Its primary purpose is
72 to implement cheap automatic dynamic loading of Perl modules.
</p>
73 <p>For a more complicated interface, see
<a href=
"file://C|\msysgit\mingw\html/lib/DynaLoader.html">the DynaLoader manpage
</a>. Many (most)
74 features of
<code>DynaLoader
</code> are not implemented in
<code>XSLoader
</code>, like for
75 example the
<code>dl_load_flags
</code>, not honored by
<code>XSLoader
</code>.
</p>
78 <h2><a name=
"migration_from_dynaloader">Migration from
<code>DynaLoader
</code></a></h2>
79 <p>A typical module using
<a href=
"file://C|\msysgit\mingw\html/lib/DynaLoader.html">DynaLoader
</a> starts like this:
</p>
82 require DynaLoader;
</pre>
84 our @ISA = qw( OnePackage OtherPackage DynaLoader );
85 our $VERSION = '
0.01';
86 bootstrap YourPackage $VERSION;
</pre>
92 our @ISA = qw( OnePackage OtherPackage );
93 our $VERSION = '
0.01';
94 XSLoader::load 'YourPackage', $VERSION;
</pre>
95 <p>In other words: replace
<code>require DynaLoader
</code> by
<code>use XSLoader
</code>, remove
96 <code>DynaLoader
</code> from
<code>@ISA
</code>, change
<code>bootstrap
</code> by
<code>XSLoader::load
</code>. Do not
97 forget to quote the name of your package on the
<code>XSLoader::load
</code> line,
98 and add comma (
<code>,
</code>) before the arguments (
<code>$VERSION
</code> above).
</p>
99 <p>Of course, if
<code>@ISA
</code> contained only
<code>DynaLoader
</code>, there is no need to have
100 the
<code>@ISA
</code> assignment at all; moreover, if instead of
<a href=
"file://C|\msysgit\mingw\html/pod/perlfunc.html#item_our"><code>our
</code></a> one uses the
101 more backward-compatible
</p>
103 use vars qw($VERSION @ISA);
</pre>
104 <p>one can remove this reference to
<code>@ISA
</code> together with the
<code>@ISA
</code> assignment.
</p>
105 <p>If no
<code>$VERSION
</code> was specified on the
<code>bootstrap
</code> line, the last line becomes
</p>
107 XSLoader::load 'YourPackage';
</pre>
110 <h2><a name=
"backward_compatible_boilerplate">Backward compatible boilerplate
</a></h2>
111 <p>If you want to have your cake and eat it too, you need a more complicated
115 use vars qw($VERSION @ISA);
</pre>
117 @ISA = qw( OnePackage OtherPackage );
121 XSLoader::load('YourPackage', $VERSION);
125 push @ISA, 'DynaLoader';
126 bootstrap YourPackage $VERSION;
128 <p>The parentheses about
<a href=
"#item_load"><code>XSLoader::load()
</code></a> arguments are needed since we replaced
129 <code>use XSLoader
</code> by
<a href=
"file://C|\msysgit\mingw\html/pod/perlfunc.html#item_require"><code>require
</code></a>, so the compiler does not know that a function
130 <a href=
"#item_load"><code>XSLoader::load()
</code></a> is present.
</p>
131 <p>This boilerplate uses the low-overhead
<code>XSLoader
</code> if present; if used with
132 an antic Perl which has no
<code>XSLoader
</code>, it falls back to using
<code>DynaLoader
</code>.
</p>
136 <h1><a name=
"order_of_initialization__early_load__">Order of initialization: early
<a href=
"#item_load"><code>load()
</code></a></a></h1>
137 <p><em>Skip this section if the XSUB functions are supposed to be called from other
138 modules only; read it only if you call your XSUBs from the code in your module,
139 or have a
<code>BOOT:
</code> section in your XS file (see
<a href=
"file://C|\msysgit\mingw\html/pod/perlxs.html#the_boot__keyword">The BOOT: Keyword in the perlxs manpage
</a>).
140 What is described here is equally applicable to the
<a href=
"file://C|\msysgit\mingw\html/lib/DynaLoader.html">DynaLoader
</a>
142 <p>A sufficiently complicated module using XS would have both Perl code (defined
143 in
<em>YourPackage.pm
</em>) and XS code (defined in
<em>YourPackage.xs
</em>). If this
144 Perl code makes calls into this XS code, and/or this XS code makes calls to
145 the Perl code, one should be careful with the order of initialization.
</p>
146 <p>The call to
<a href=
"#item_load"><code>XSLoader::load()
</code></a> (or
<code>bootstrap()
</code>) has three side effects:
</p>
149 <p>if
<code>$VERSION
</code> was specified, a sanity check is done to ensure that the
150 versions of the
<em>.pm
</em> and the (compiled)
<em>.xs
</em> parts are compatible;
</p>
153 <p>the XSUBs are made accessible from Perl;
</p>
156 <p>if a
<code>BOOT:
</code> section was present in the
<em>.xs
</em> file, the code there is called.
</p>
159 <p>Consequently, if the code in the
<em>.pm
</em> file makes calls to these XSUBs, it is
160 convenient to have XSUBs installed before the Perl code is defined; for
161 example, this makes prototypes for XSUBs visible to this Perl code.
162 Alternatively, if the
<code>BOOT:
</code> section makes calls to Perl functions (or
163 uses Perl variables) defined in the
<em>.pm
</em> file, they must be defined prior to
164 the call to
<a href=
"#item_load"><code>XSLoader::load()
</code></a> (or
<code>bootstrap()
</code>).
</p>
165 <p>The first situation being much more frequent, it makes sense to rewrite the
170 use vars qw($VERSION @ISA);
</pre>
173 @ISA = qw( OnePackage OtherPackage );
174 $VERSION = '
0.01';
</pre>
176 # Put Perl code used in the BOOT: section here
</pre>
178 XSLoader::load 'YourPackage', $VERSION;
181 # Put Perl code making calls into XSUBs here
</pre>
184 <h2><a name=
"the_most_hairy_case">The most hairy case
</a></h2>
185 <p>If the interdependence of your
<code>BOOT:
</code> section and Perl code is
186 more complicated than this (e.g., the
<code>BOOT:
</code> section makes calls to Perl
187 functions which make calls to XSUBs with prototypes), get rid of the
<code>BOOT:
</code>
188 section altogether. Replace it with a function
<code>onBOOT()
</code>, and call it like
193 use vars qw($VERSION @ISA);
</pre>
196 @ISA = qw( OnePackage OtherPackage );
198 XSLoader::load 'YourPackage', $VERSION;
201 # Put Perl code used in onBOOT() function here; calls to XSUBs are
202 # prototype-checked.
</pre>
206 # Put Perl initialization code assuming that XS is initialized here
</pre>
210 <h1><a name=
"diagnostics">DIAGNOSTICS
</a></h1>
212 <dt><strong><a name=
"item_can_27t_find__27_25s_27_symbol_in__25s">Can't find '%s' symbol in %s
</a></strong>
215 <p><strong>(F)
</strong> The bootstrap symbol could not be found in the extension module.
</p>
218 <dt><strong><a name=
"item_can_27t_load__27_25s_27_for_module__25s_3a__25s">Can't load '%s' for module %s: %s
</a></strong>
221 <p><strong>(F)
</strong> The loading or initialisation of the extension module failed.
222 The detailed error follows.
</p>
225 <dt><strong><a name=
"item_undefined_symbols_present_after_loading__25s_3a__2">Undefined symbols present after loading %s: %s
</a></strong>
228 <p><strong>(W)
</strong> As the message says, some symbols stay undefined although the
229 extension module was correctly loaded and initialised. The list of undefined
233 <dt><strong><a name=
"item_load">XSLoader::load('Your::Module', $Your::Module::VERSION)
</a></strong>
236 <p><strong>(F)
</strong> You tried to invoke
<a href=
"#item_load"><code>load()
</code></a> without any argument. You must supply
237 a module name, and optionally its version.
</p>
244 <h1><a name=
"limitations">LIMITATIONS
</a></h1>
245 <p>To reduce the overhead as much as possible, only one possible location
246 is checked to find the extension DLL (this location is where
<code>make install
</code>
247 would put the DLL). If not found, the search for the DLL is transparently
248 delegated to
<code>DynaLoader
</code>, which looks for the DLL along the
<a href=
"file://C|\msysgit\mingw\html/pod/perlvar.html#item__inc"><code>@INC
</code></a> list.
</p>
249 <p>In particular, this is applicable to the structure of
<a href=
"file://C|\msysgit\mingw\html/pod/perlvar.html#item__inc"><code>@INC
</code></a> used for testing
250 not-yet-installed extensions. This means that running uninstalled extensions
251 may have much more overhead than running the same extensions after
252 <code>make install
</code>.
</p>
256 <h1><a name=
"bugs">BUGS
</a></h1>
257 <p>Please report any bugs or feature requests via the
<code>perlbug(
1)
</code> utility.
</p>
261 <h1><a name=
"see_also">SEE ALSO
</a></h1>
262 <p><a href=
"file://C|\msysgit\mingw\html/lib/DynaLoader.html">the DynaLoader manpage
</a></p>
266 <h1><a name=
"authors">AUTHORS
</a></h1>
267 <p>Ilya Zakharevich originally extracted
<code>XSLoader
</code> from
<code>DynaLoader
</code>.
</p>
268 <p>CPAN version is currently maintained by S
ébastien Aperghis-Tramoni
269 <<a href=
"mailto:sebastien@aperghis.net">sebastien@aperghis.net
</a>></p>
270 <p>Previous maintainer was Michael G Schwern
<<a href=
"mailto:schwern@pobox.com">schwern@pobox.com
</a>></p>
274 <h1><a name=
"copyright">COPYRIGHT
</a></h1>
275 <p>This program is free software; you can redistribute it and/or modify
276 it under the same terms as Perl itself.
</p>
277 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
278 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
279 <big><strong><span class=
"block"> XSLoader - Dynamically load C libraries into Perl code
</span></strong></big>