mingw/html/lib/XSLoader.html

   1 <?xml version="1.0" ?>
   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">
   4 <head>
   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:" />
   8 </head>
   9
  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">&nbsp;XSLoader - Dynamically load C libraries into Perl code</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  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>
  26         <ul>
  27
  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>
  30         </ul>
  31
  32         <li><a href="#order_of_initialization__early_load__">Order of initialization: early <code>load()</code></a></li>
  33         <ul>
  34
  35                 <li><a href="#the_most_hairy_case">The most hairy case</a></li>
  36         </ul>
  37
  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>
  44 </ul>
  45 <!-- INDEX END -->
  46
  47 <hr />
  48 <p>
  49 </p>
  50 <h1><a name="name">NAME</a></h1>
  51 <p>XSLoader - Dynamically load C libraries into Perl code</p>
  52 <p>
  53 </p>
  54 <hr />
  55 <h1><a name="version">VERSION</a></h1>
  56 <p>Version 0.06</p>
  57 <p>
  58 </p>
  59 <hr />
  60 <h1><a name="synopsis">SYNOPSIS</a></h1>
  61 <pre>
  62     package YourPackage;
  63     use XSLoader;</pre>
  64 <pre>
  65     XSLoader::load 'YourPackage', $YourPackage::VERSION;</pre>
  66 <p>
  67 </p>
  68 <hr />
  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>
  76 <p>
  77 </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>
  80 <pre>
  81     package YourPackage;
  82     require DynaLoader;</pre>
  83 <pre>
  84     our @ISA = qw( OnePackage OtherPackage DynaLoader );
  85     our $VERSION = '0.01';
  86     bootstrap YourPackage $VERSION;</pre>
  87 <p>Change this to</p>
  88 <pre>
  89     package YourPackage;
  90     use XSLoader;</pre>
  91 <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>
 102 <pre>
 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>
 106 <pre>
 107     XSLoader::load 'YourPackage';</pre>
 108 <p>
 109 </p>
 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
 112 boilerplate.</p>
 113 <pre>
 114     package YourPackage;
 115     use vars qw($VERSION @ISA);</pre>
 116 <pre>
 117     @ISA = qw( OnePackage OtherPackage );
 118     $VERSION = '0.01';
 119     eval {
 120        require XSLoader;
 121        XSLoader::load('YourPackage', $VERSION);
 122        1;
 123     } or do {
 124        require DynaLoader;
 125        push @ISA, 'DynaLoader';
 126        bootstrap YourPackage $VERSION;
 127     };</pre>
 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>
 133 <p>
 134 </p>
 135 <hr />
 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>
 141 interface.</em></p>
 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>
 147 <ul>
 148 <li>
 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>
 151 </li>
 152 <li>
 153 <p>the XSUBs are made accessible from Perl;</p>
 154 </li>
 155 <li>
 156 <p>if a <code>BOOT:</code> section was present in the <em>.xs</em> file, the code there is called.</p>
 157 </li>
 158 </ul>
 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
 166 boilerplate as</p>
 167 <pre>
 168     package YourPackage;
 169     use XSLoader;
 170     use vars qw($VERSION @ISA);</pre>
 171 <pre>
 172     BEGIN {
 173        @ISA = qw( OnePackage OtherPackage );
 174        $VERSION = '0.01';</pre>
 175 <pre>
 176        # Put Perl code used in the BOOT: section here</pre>
 177 <pre>
 178        XSLoader::load 'YourPackage', $VERSION;
 179     }</pre>
 180 <pre>
 181     # Put Perl code making calls into XSUBs here</pre>
 182 <p>
 183 </p>
 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
 189 this:</p>
 190 <pre>
 191     package YourPackage;
 192     use XSLoader;
 193     use vars qw($VERSION @ISA);</pre>
 194 <pre>
 195     BEGIN {
 196        @ISA = qw( OnePackage OtherPackage );
 197        $VERSION = '0.01';
 198        XSLoader::load 'YourPackage', $VERSION;
 199     }</pre>
 200 <pre>
 201     # Put Perl code used in onBOOT() function here; calls to XSUBs are
 202     # prototype-checked.</pre>
 203 <pre>
 204     onBOOT;</pre>
 205 <pre>
 206     # Put Perl initialization code assuming that XS is initialized here</pre>
 207 <p>
 208 </p>
 209 <hr />
 210 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 211 <dl>
 212 <dt><strong><a name="item_can_27t_find__27_25s_27_symbol_in__25s">Can't find '%s' symbol in %s</a></strong>
 213
 214 <dd>
 215 <p><strong>(F)</strong> The bootstrap symbol could not be found in the extension module.</p>
 216 </dd>
 217 </li>
 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>
 219
 220 <dd>
 221 <p><strong>(F)</strong> The loading or initialisation of the extension module failed.
 222 The detailed error follows.</p>
 223 </dd>
 224 </li>
 225 <dt><strong><a name="item_undefined_symbols_present_after_loading__25s_3a__2">Undefined symbols present after loading %s: %s</a></strong>
 226
 227 <dd>
 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
 230 symbols follows.</p>
 231 </dd>
 232 </li>
 233 <dt><strong><a name="item_load">XSLoader::load('Your::Module', $Your::Module::VERSION)</a></strong>
 234
 235 <dd>
 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>
 238 </dd>
 239 </li>
 240 </dl>
 241 <p>
 242 </p>
 243 <hr />
 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>
 253 <p>
 254 </p>
 255 <hr />
 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>
 258 <p>
 259 </p>
 260 <hr />
 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>
 263 <p>
 264 </p>
 265 <hr />
 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&eacute;bastien Aperghis-Tramoni
 269 &lt;<a href="mailto:sebastien@aperghis.net">sebastien@aperghis.net</a>&gt;</p>
 270 <p>Previous maintainer was Michael G Schwern &lt;<a href="mailto:schwern@pobox.com">schwern@pobox.com</a>&gt;</p>
 271 <p>
 272 </p>
 273 <hr />
 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">&nbsp;XSLoader - Dynamically load C libraries into Perl code</span></strong></big>
 280 </td></tr>
 281 </table>
 282
 283 </body>
 284
 285 </html>