CINXE.COM
XSLoader - Dynamically load C libraries into Perl code - metacpan.org
<!DOCTYPE html> <html lang="en-US"> <head> <title>XSLoader - Dynamically load C libraries into Perl code - metacpan.org</title> <link rel="preload" as="fetch" href="/account/login_status" crossorigin="anonymous" /> <link href="/assets/style-XFEQ536G.css" rel="stylesheet" type="text/css"> <script src="/assets/main-WXBSEDQJ.js" type="module"></script> <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of XSLoader - MetaCPAN" href="/dist/XSLoader/releases.rss" /> <link rel="canonical" href="https://metacpan.org/pod/XSLoader" /> <meta name="description" content="Dynamically load C libraries into Perl code" /> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5"> <link rel="shortcut icon" href="/static/icons/favicon.ico"> <link rel="apple-touch-icon" sizes="152x152" href="/static/icons/apple-touch-icon.png"> <link rel="search" href="/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN"> <script async src="https://perl-ads.perlhacks.com/perl-ads.js"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=G-E82Q2V8LVD"></script> <meta property="og:site_name" content="MetaCPAN" /> <meta name="twitter:site" content="@metacpan" /> <meta property="og:type" content="article" /> <meta name="twitter:card" content="summary" /> <meta property="og:url" content="https://metacpan.org/pod/XSLoader" /> <meta property="og:title" content="XSLoader" /> <meta property="og:description" content="Dynamically load C libraries into Perl code" /> <meta property="og:image" content="https://metacpan.org/static/images/dots.png" /> </head> <body> <nav class="navbar navbar-default" role="navigation"> <div class="header-logo-large hidden-xs"> <a href="/" tabindex="0"> <svg class="logo" aria-label="MetaCPAN"> <use class="logo" href="/static/images/metacpan-logo.svg#logo" /> </svg> </a> </div> <div class="header-logo-icon visible-xs"> <a href="/"> <svg class="logo" aria-label="MetaCPAN"> <use class="logo" href="/static/images/metacpan-logo.svg#dots" /> </svg> </a> </div> <ul class="nav navbar-nav menu-items hidden-xs hidden-sm"> <li><a href="/about">About</a></li> <li><a href="/about/sponsors">Sponsor</a></li> <li><a href="https://grep.metacpan.org/">grep::cpan</a></li> <li><a href="/recent">Recent</a></li> <li><a href="/about/faq">FAQ</a></li> <li><a href="/tools">Tools</a></li> <li><a href="https://fastapi.metacpan.org/">API</a></li> </ul> <ul class="nav navbar-nav navbar-right"> <button type="button" class="searchbar-btn visible-xs visible-sm"> <i class="fa fa-search button-fa-icon"></i> </button> <form action="/search" class="searchbar-form visible-md visible-lg search-form form-horizontal"> <input type="hidden" name="size" id="metacpan_search-size" value="20"> <div class="form-group"> <div class="search-group"> <i class="fa fa-search"></i> <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value=""> </div> </div> </form> <li class="icon-slidepanel visible-xs visible-sm"> <button data-toggle="slidepanel" data-target=".slidepanel"> <span class="button-fa-icon"> <i class="fa fa-bars slidepanel-open"></i> <i class="fa fa-times slidepanel-close"></i> </span> </button> </li> <li class="dropdown login-dropdown show-logged-in"> <button type="button" class="dropdown-toggle" data-toggle="dropdown"> <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i> <i class="fas fa-chevron-down"></i> </button> <ul class="dropdown-menu"> <li><a href="/account/identities">Identities</a></li> <li><a href="/account/profile">Profile</a></li> <li><a href="/account/favorite/list">Favorites</a></li> <li> <a href="#" type="button" class="logout-button"> Logout </a> </li> </ul> </li> <li class="dropdown login-dropdown show-logged-out"> <button type="button" class="dropdown-toggle" data-toggle="dropdown"> <i class="fa fa-user button-fa-icon avatar-placeholder" aria-hidden="true"></i> <i class="fas fa-chevron-down"></i> </button> <ul class="dropdown-menu"> <li> <a href="/login/github"> <i class="fab fa-github fa-fw"></i> GitHub </a> </li> <li> <a href="/login/twitter"> <i class="fab fa-twitter fa-fw"></i> Twitter </a> </li> <li> <a href="/login/google"> <i class="fab fa-google fa-fw"></i> Google </a> </li> </ul> </li> <li class="dropdown login-dropdown hide-logged-in hide-logged-out"> <button> <i class="fa fa-user button-fa-icon" aria-hidden="true"></i> </button> </li> </ul> </nav> <div class="page-content "> <div id="perl-ad-target" class="top-notify-banner perl-ad-target"> </div> <nav class="sidebar"> <div class="slidepanel"> <ul class="nav-list "> <li class="nav-header no-margin-top"> <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of XSLoader was released."> <span class="relatize">01 Sep 2016 13:04:09 UTC</span> </div> </li> <li> Distribution: <a href="/dist/XSLoader">XSLoader</a> </li> <li> Module version: 0.24 </li> <li> <a data-keyboard-shortcut="g s" href="/dist/XSLoader/source/XSLoader_pm.PL">Source</a> (<a href="/dist/XSLoader/source/XSLoader_pm.PL?raw=1">raw</a>) </li> <li> <a data-keyboard-shortcut="g p" href="/dist/XSLoader/source/XSLoader.pm">Pod Source</a> (<a href="/dist/XSLoader/source/XSLoader.pm?raw=1">raw</a>) </li> <li> <a data-keyboard-shortcut="g b" href="/dist/XSLoader/source">Browse</a> (<a href="/dist/XSLoader/source?raw=1">raw</a>) </li> <li> <a data-keyboard-shortcut="g c" href="/dist/XSLoader/changes">Changes</a> </li> <li> <a rel="noopener nofollow" class="nopopup" href="https://metacpan.org/module/XSLoader">Homepage</a> </li> <li> <a class="nopopup" href="/dist/XSLoader/contribute">How to Contribute</a> </li> <li> <a rel="noopener nofollow" href="git://perl5.git.perl.org/perl.git">Clone git repository</a> </li> <li> <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.perl.org/rt3/Search/Results.html?Query=Queue='perl5' AND Content LIKE 'module=XSLoader' AND (Status='open' OR Status='new' OR Status='stalled')">Issues</a> </li> <li> <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=XSLoader+0.24" title="Matrix">Testers</a> <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/X/XSLoader.html?oncpan=1&distmat=1&version=0.24&grade=2" style="color: #090">989</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/X/XSLoader.html?oncpan=1&distmat=1&version=0.24&grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/X/XSLoader.html?oncpan=1&distmat=1&version=0.24&grade=4">0</a>)</span> </li> <li> <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/SAPER/XSLoader-0.24">Kwalitee</a> </li> <li> <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on XSLoader who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)"> Bus factor: 5 </div> </li> <li> <a rel="noopener nofollow" href="http://cpancover.com/latest/XSLoader-0.24/index.html">1.39% Coverage </a> </li> <li> License: perl_5 </li> <li class="chat-banner"> <div><a rel="noopener nofollow" target="_blank" href="https://kiwiirc.com/nextclient/#irc://irc.perl.org/#p5p?nick=mc-guest-?">Chat with us!</a></div> </li> <li class="nav-header">Activity</li> <li> <div class="activity-graph"> <img src="/dist/XSLoader/activity.svg?res=month" /> <div class="comment">24 month</div> </div> </li> <li class="nav-header">Tools</li> <li> <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/S/SA/SAPER/XSLoader-0.24.tar.gz"> Download (<span itemprop="fileSize">13KB</span>)</a> </li> <li> <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FSAPER%2FXSLoader-0.24%2FXSLoader_pm.PL"> MetaCPAN Explorer </a> </li> <li> <a href="/dist/XSLoader/permissions"> Permissions </a> </li> <li> <a href="/dist/XSLoader/releases.rss"> Subscribe to distribution </a> </li> <li> <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog"> Install Instructions </button> </li> <li> <form action="/search"> <input type="hidden" name="q" value="dist:XSLoader"> <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form"> <input type="submit" style="display: none"> </form> </li> <li> <form action="https://grep.metacpan.org/search"> <input type="hidden" name="qd" value="XSLoader"> <input type="hidden" name="source" value="metacpan"> <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form"> <input type="submit" style="display: none"> </form> </li> <li class="version-jump"> <select class="select-navigator form-control tool-bar-form"> <option disabled selected>Jump to version</option> <option disabled value="/release/SAPER/XSLoader-0.24/view/XSLoader_pm.PL" >0.24 (SAPER on 2016-09-01)</option> <option value="/release/SAPER/XSLoader-0.23/view/XSLoader_pm.PL" >0.23 (SAPER on 2016-08-31)</option> <option value="/release/SAPER/XSLoader-0.22/view/XSLoader_pm.PL" >0.22 (SAPER on 2016-07-05)</option> <option value="/release/SAPER/XSLoader-0.20/view/XSLoader_pm.PL" >0.20 (SAPER on 2016-05-06)</option> <option value="/release/SAPER/XSLoader-0.16/view/XSLoader_pm.PL" >0.16 (SAPER on 2012-09-03)</option> <optgroup label="BackPAN">' <option value="/release/SAPER/XSLoader-0.15/view/XSLoader_pm.PL" >0.15 (SAPER on 2011-04-17)</option> <option value="/release/SAPER/XSLoader-0.14/view/XSLoader_pm.PL" >0.14 (SAPER on 2011-04-16)</option> <option value="/release/SAPER/XSLoader-0.10/view/XSLoader_pm.PL" >0.10 (SAPER on 2008-09-25)</option> <option value="/release/SAPER/XSLoader-0.09/view/XSLoader_pm.PL" >0.09 (SAPER on 2008-09-21)</option> <option value="/release/SAPER/XSLoader-0.08/view/XSLoader_pm.PL" >0.08 (SAPER on 2007-04-29)</option> <option value="/release/SAPER/XSLoader-0.07/view/XSLoader_pm.PL" >0.07 (SAPER on 2006-10-13)</option> <option value="/release/SAPER/XSLoader-0.06/view/XSLoader_pm.PL" >0.06 (SAPER on 2005-10-16)</option> <option value="/release/SAPER/XSLoader-0.05/view/XSLoader_pm.PL" >0.05 (SAPER on 2005-09-30)</option> <option value="/release/SAPER/XSLoader-0.04/view/XSLoader_pm.PL" >0.04 (SAPER on 2005-09-26)</option> <option value="/release/MSCHWERN/XSLoader-0.03_01/view/XSLoader_pm.PL" >0.03_01 DEV (MSCHWERN on 2004-12-07)</option> </optgroup> </select> </li> <li class="version-diff"> <select class="select-navigator form-control tool-bar-form"> <option disabled selected>Diff with version</option> <option disabled value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.24/XSLoader_pm.PL" >0.24 (SAPER on 2016-09-01)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.23/XSLoader_pm.PL" >0.23 (SAPER on 2016-08-31)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.22/XSLoader_pm.PL" >0.22 (SAPER on 2016-07-05)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.20/XSLoader_pm.PL" >0.20 (SAPER on 2016-05-06)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.16/XSLoader_pm.PL" >0.16 (SAPER on 2012-09-03)</option> <optgroup label="BackPAN">' <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.15/XSLoader_pm.PL" >0.15 (SAPER on 2011-04-17)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.14/XSLoader_pm.PL" >0.14 (SAPER on 2011-04-16)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.10/XSLoader_pm.PL" >0.10 (SAPER on 2008-09-25)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.09/XSLoader_pm.PL" >0.09 (SAPER on 2008-09-21)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.08/XSLoader_pm.PL" >0.08 (SAPER on 2007-04-29)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.07/XSLoader_pm.PL" >0.07 (SAPER on 2006-10-13)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.06/XSLoader_pm.PL" >0.06 (SAPER on 2005-10-16)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.05/XSLoader_pm.PL" >0.05 (SAPER on 2005-09-30)</option> <option value="/release/SAPER/XSLoader-0.24/diff/SAPER/XSLoader-0.04/XSLoader_pm.PL" >0.04 (SAPER on 2005-09-26)</option> <option value="/release/SAPER/XSLoader-0.24/diff/MSCHWERN/XSLoader-0.03_01/XSLoader_pm.PL" >0.03_01 DEV (MSCHWERN on 2004-12-07)</option> </optgroup> </select> </li> <li> <ul class="dependencies"> <li class="nav-header">Dependencies</li> <li><a href="/pod/Test::More" title="Test::More" class="ellipsis">Test::More</a></li> <li> <hr> </li> <li> <a href="/module/XSLoader/requires">Reverse dependencies</a> </li> <li> <a href="http://deps.cpantesters.org/?module=XSLoader">CPAN Testers List</a> </li> <li> <a href="https://cpandeps.grinnz.com/?dist=XSLoader">Dependency graph</a> </li> </ul> </li> <li class="nav-header">Permalinks</li> <li> <a href="/release/SAPER/XSLoader-0.24/view/XSLoader_pm.PL">This version</a> </li> <li> <a href="/pod/XSLoader">Latest version</a> </li> <li> <div class="plussers"> <div class="nav-header">++ed by:</div> <div> <a class="display-all" href="/author/RWP"><img src="https://www.gravatar.com/avatar/7110eb2389e69a066d9d7cad7a1cc2bf?d=identicon&s=20" title="RWP" alt="RWP"></a> <a class="display-all" href="/author/RRWO"><img src="https://www.gravatar.com/avatar/4a5274bc5d690ee3d619f044778771a7?d=identicon&s=20" title="RRWO" alt="RRWO"></a> <a class="display-all" href="/author/GFUJI"><img src="https://www.gravatar.com/avatar/9278c3a06b8d8752fb913dea93f959c1?d=identicon&s=20" title="GFUJI" alt="GFUJI"></a> </div> <!-- Display counts of plussers--> <div> <a href="/dist/XSLoader/plussers">3 PAUSE users</a> </div> <div> 3 non-PAUSE users </div> </div> </li> <li> <div> <button class="contributors-show-button btn-link">and 1 contributors</button> <div id="metacpan_contributors" class="slide-out slide-out-hidden"> <div> <ul> <li class="contributor" data-contrib-email="sebastien@aperghis.net" > <img class="gravatar" width="20" height="20" src="https://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e?d=identicon&s=20" /> Sebastien Aperghis-Tramoni </li> </ul> </div> </div> </div> </li> </ul> </div> </nav> <div class="content-navigation"> <div class="breadcrumbs"> <span> <a data-keyboard-shortcut="g a" rel="author" href="/author/SAPER" class="author-name">Sébastien Aperghis-Tramoni</a> </span> <span> / </span> <div class="release dist-release status-latest maturity-released"> <span class="dropdown"><b class="caret"></b></span> <select class="select-navigator "> <option selected value="/release/SAPER/XSLoader-0.24/view/XSLoader_pm.PL" >0.24 (SAPER on 2016-09-01)</option> <option value="/release/SAPER/XSLoader-0.23/view/XSLoader_pm.PL" >0.23 (SAPER on 2016-08-31)</option> <option value="/release/SAPER/XSLoader-0.22/view/XSLoader_pm.PL" >0.22 (SAPER on 2016-07-05)</option> <option value="/release/SAPER/XSLoader-0.20/view/XSLoader_pm.PL" >0.20 (SAPER on 2016-05-06)</option> <option value="/release/SAPER/XSLoader-0.16/view/XSLoader_pm.PL" >0.16 (SAPER on 2012-09-03)</option> <optgroup label="BackPAN">' <option value="/release/SAPER/XSLoader-0.15/view/XSLoader_pm.PL" >0.15 (SAPER on 2011-04-17)</option> <option value="/release/SAPER/XSLoader-0.14/view/XSLoader_pm.PL" >0.14 (SAPER on 2011-04-16)</option> <option value="/release/SAPER/XSLoader-0.10/view/XSLoader_pm.PL" >0.10 (SAPER on 2008-09-25)</option> <option value="/release/SAPER/XSLoader-0.09/view/XSLoader_pm.PL" >0.09 (SAPER on 2008-09-21)</option> <option value="/release/SAPER/XSLoader-0.08/view/XSLoader_pm.PL" >0.08 (SAPER on 2007-04-29)</option> <option value="/release/SAPER/XSLoader-0.07/view/XSLoader_pm.PL" >0.07 (SAPER on 2006-10-13)</option> <option value="/release/SAPER/XSLoader-0.06/view/XSLoader_pm.PL" >0.06 (SAPER on 2005-10-16)</option> <option value="/release/SAPER/XSLoader-0.05/view/XSLoader_pm.PL" >0.05 (SAPER on 2005-09-30)</option> <option value="/release/SAPER/XSLoader-0.04/view/XSLoader_pm.PL" >0.04 (SAPER on 2005-09-26)</option> <option value="/release/MSCHWERN/XSLoader-0.03_01/view/XSLoader_pm.PL" >0.03_01 DEV (MSCHWERN on 2004-12-07)</option> </optgroup> </select> <a data-keyboard-shortcut="g d" class="release-name" href="/dist/XSLoader">XSLoader-0.24</a> </div> <span class="river-gauge-gauge"> <svg width="24px" height="15px" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <g> <title> River stage five • 460 direct dependents • 23927 total dependents </title> <rect x="0" y="0" width="4" height="15" fill="#7ea3f2" /> <rect x="5" y="0" width="4" height="15" fill="#7ea3f2" /> <rect x="10" y="0" width="4" height="15" fill="#7ea3f2" /> <rect x="15" y="0" width="4" height="15" fill="#7ea3f2" /> <rect x="20" y="0" width="4" height="15" fill="#7ea3f2" /> </g> </svg> </span> <div id="XSLoader-fav" class="show-logged-in"> <form action="/account/favorite/add" style="display: inline" method="POST"> <input type="hidden" name="remove" value="0"> <input type="hidden" name="release" value="XSLoader-0.24"> <input type="hidden" name="author" value="SAPER"> <input type="hidden" name="distribution" value="XSLoader"> <button type="submit" class="favorite highlight"><span>6</span> ++</button> </form> </div> <div class="show-logged-out"> <button class="fav-not-logged-in favorite highlight"><span>6</span> ++</button> </div> / <span>XSLoader</span> </div> </div> <main class="content"> <nav class="toc"> <div class="toc-header"><strong>Contents</strong></div> <ul> <li><a href="#NAME">NAME</a></li> <li><a href="#VERSION">VERSION</a></li> <li><a href="#SYNOPSIS">SYNOPSIS</a></li> <li><a href="#DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#Migration-from-DynaLoader">Migration from DynaLoader</a></li> <li><a href="#Backward-compatible-boilerplate">Backward compatible boilerplate</a></li> </ul> </li> <li><a href="#Order-of-initialization%3A-early-load()">Order of initialization: early load()</a> <ul> <li><a href="#The-most-hairy-case">The most hairy case</a></li> </ul> </li> <li><a href="#DIAGNOSTICS">DIAGNOSTICS</a></li> <li><a href="#LIMITATIONS">LIMITATIONS</a></li> <li><a href="#KNOWN-BUGS">KNOWN BUGS</a></li> <li><a href="#BUGS">BUGS</a></li> <li><a href="#SEE-ALSO">SEE ALSO</a></li> <li><a href="#AUTHORS">AUTHORS</a></li> <li><a href="#COPYRIGHT-%26-LICENSE">COPYRIGHT & LICENSE</a></li> </ul></nav> <div class="pod anchors"> <h1 id="NAME">NAME</h1> <p>XSLoader - Dynamically load C libraries into Perl code</p> <h1 id="VERSION">VERSION</h1> <p>Version 0.24</p> <h1 id="SYNOPSIS">SYNOPSIS</h1> <pre><code>package YourPackage; require XSLoader; XSLoader::load();</code></pre> <h1 id="DESCRIPTION">DESCRIPTION</h1> <p>This module defines a standard <i>simplified</i> interface to the dynamic linking mechanisms available on many platforms. Its primary purpose is to implement cheap automatic dynamic loading of Perl modules.</p> <p>For a more complicated interface, see <a href="/pod/DynaLoader">DynaLoader</a>. Many (most) features of <code>DynaLoader</code> are not implemented in <code>XSLoader</code>, like for example the <code>dl_load_flags</code>, not honored by <code>XSLoader</code>.</p> <h2 id="Migration-from-DynaLoader"><a id="Migration"></a>Migration from <code>DynaLoader</code></h2> <p>A typical module using <a href="/pod/DynaLoader">DynaLoader</a> starts like this:</p> <pre><code>package YourPackage; require DynaLoader; our @ISA = qw( OnePackage OtherPackage DynaLoader ); our $VERSION = '0.01'; bootstrap YourPackage $VERSION;</code></pre> <p>Change this to</p> <pre><code>package YourPackage; use XSLoader; our @ISA = qw( OnePackage OtherPackage ); our $VERSION = '0.01'; XSLoader::load 'YourPackage', $VERSION;</code></pre> <p>In other words: replace <code>require DynaLoader</code> by <code>use XSLoader</code>, remove <code>DynaLoader</code> from <code>@ISA</code>, change <code>bootstrap</code> by <code>XSLoader::load</code>. Do not forget to quote the name of your package on the <code>XSLoader::load</code> line, and add comma (<code>,</code>) before the arguments (<code>$VERSION</code> above).</p> <p>Of course, if <code>@ISA</code> contained only <code>DynaLoader</code>, there is no need to have the <code>@ISA</code> assignment at all; moreover, if instead of <code>our</code> one uses the more backward-compatible</p> <pre><code>use vars qw($VERSION @ISA);</code></pre> <p>one can remove this reference to <code>@ISA</code> together with the <code>@ISA</code> assignment.</p> <p>If no <code>$VERSION</code> was specified on the <code>bootstrap</code> line, the last line becomes</p> <pre><code>XSLoader::load 'YourPackage';</code></pre> <p>If the call to <code>load</code> is from <code>YourPackage</code>, then that can be further simplified to</p> <pre><code>XSLoader::load();</code></pre> <p>as <code>load</code> will use <code>caller</code> to determine the package.</p> <h2 id="Backward-compatible-boilerplate"><a id="Backward"></a>Backward compatible boilerplate</h2> <p>If you want to have your cake and eat it too, you need a more complicated boilerplate.</p> <pre><code>package YourPackage; use vars qw($VERSION @ISA); @ISA = qw( OnePackage OtherPackage ); $VERSION = '0.01'; eval { require XSLoader; XSLoader::load('YourPackage', $VERSION); 1; } or do { require DynaLoader; push @ISA, 'DynaLoader'; bootstrap YourPackage $VERSION; };</code></pre> <p>The parentheses about <code>XSLoader::load()</code> arguments are needed since we replaced <code>use XSLoader</code> by <code>require</code>, so the compiler does not know that a function <code>XSLoader::load()</code> is present.</p> <p>This boilerplate uses the low-overhead <code>XSLoader</code> if present; if used with an antique Perl which has no <code>XSLoader</code>, it falls back to using <code>DynaLoader</code>.</p> <h1 id="Order-of-initialization:-early-load()"><a id="Order"></a><a id="Order-of-initialization:-early-load"></a>Order of initialization: early load()</h1> <p><i>Skip this section if the XSUB functions are supposed to be called from other modules only; read it only if you call your XSUBs from the code in your module, or have a <code>BOOT:</code> section in your XS file (see <a href="/pod/perlxs#The-BOOT%3A-Keyword">"The BOOT: Keyword" in perlxs</a>). What is described here is equally applicable to the <a href="/pod/DynaLoader">DynaLoader</a> interface.</i></p> <p>A sufficiently complicated module using XS would have both Perl code (defined in <i>YourPackage.pm</i>) and XS code (defined in <i>YourPackage.xs</i>). If this Perl code makes calls into this XS code, and/or this XS code makes calls to the Perl code, one should be careful with the order of initialization.</p> <p>The call to <code>XSLoader::load()</code> (or <code>bootstrap()</code>) calls the module's bootstrap code. For modules build by <i>xsubpp</i> (nearly all modules) this has three side effects:</p> <ul> <li><p>A sanity check is done to ensure that the versions of the <i>.pm</i> and the (compiled) <i>.xs</i> parts are compatible. If <code>$VERSION</code> was specified, this is used for the check. If not specified, it defaults to <code>$XS_VERSION // $VERSION</code> (in the module's namespace)</p> </li> <li><p>the XSUBs are made accessible from Perl</p> </li> <li><p>if a <code>BOOT:</code> section was present in the <i>.xs</i> file, the code there is called.</p> </li> </ul> <p>Consequently, if the code in the <i>.pm</i> file makes calls to these XSUBs, it is convenient to have XSUBs installed before the Perl code is defined; for example, this makes prototypes for XSUBs visible to this Perl code. Alternatively, if the <code>BOOT:</code> section makes calls to Perl functions (or uses Perl variables) defined in the <i>.pm</i> file, they must be defined prior to the call to <code>XSLoader::load()</code> (or <code>bootstrap()</code>).</p> <p>The first situation being much more frequent, it makes sense to rewrite the boilerplate as</p> <pre><code>package YourPackage; use XSLoader; use vars qw($VERSION @ISA); BEGIN { @ISA = qw( OnePackage OtherPackage ); $VERSION = '0.01'; # Put Perl code used in the BOOT: section here XSLoader::load 'YourPackage', $VERSION; } # Put Perl code making calls into XSUBs here</code></pre> <h2 id="The-most-hairy-case"><a id="The"></a>The most hairy case</h2> <p>If the interdependence of your <code>BOOT:</code> section and Perl code is more complicated than this (e.g., the <code>BOOT:</code> section makes calls to Perl functions which make calls to XSUBs with prototypes), get rid of the <code>BOOT:</code> section altogether. Replace it with a function <code>onBOOT()</code>, and call it like this:</p> <pre><code>package YourPackage; use XSLoader; use vars qw($VERSION @ISA); BEGIN { @ISA = qw( OnePackage OtherPackage ); $VERSION = '0.01'; XSLoader::load 'YourPackage', $VERSION; } # Put Perl code used in onBOOT() function here; calls to XSUBs are # prototype-checked. onBOOT; # Put Perl initialization code assuming that XS is initialized here</code></pre> <h1 id="DIAGNOSTICS">DIAGNOSTICS</h1> <dl> <dt id="Can't-find-'%s'-symbol-in-%s"><a id="Can"></a><a id="Cant-find-s-symbol-in-s"></a><code>Can't find '%s' symbol in %s</code></dt> <dd> <p><b>(F)</b> The bootstrap symbol could not be found in the extension module.</p> </dd> <dt id="Can't-load-'%s'-for-module-%s:-%s"><a id="Can1"></a><a id="Cant-load-s-for-module-s:-s"></a><code>Can't load '%s' for module %s: %s</code></dt> <dd> <p><b>(F)</b> The loading or initialisation of the extension module failed. The detailed error follows.</p> </dd> <dt id="Undefined-symbols-present-after-loading-%s:-%s"><a id="Undefined"></a><a id="Undefined-symbols-present-after-loading-s:-s"></a><code>Undefined symbols present after loading %s: %s</code></dt> <dd> <p><b>(W)</b> As the message says, some symbols stay undefined although the extension module was correctly loaded and initialised. The list of undefined symbols follows.</p> </dd> </dl> <h1 id="LIMITATIONS">LIMITATIONS</h1> <p>To reduce the overhead as much as possible, only one possible location is checked to find the extension DLL (this location is where <code>make install</code> would put the DLL). If not found, the search for the DLL is transparently delegated to <code>DynaLoader</code>, which looks for the DLL along the <code>@INC</code> list.</p> <p>In particular, this is applicable to the structure of <code>@INC</code> used for testing not-yet-installed extensions. This means that running uninstalled extensions may have much more overhead than running the same extensions after <code>make install</code>.</p> <h1 id="KNOWN-BUGS"><a id="KNOWN"></a>KNOWN BUGS</h1> <p>The new simpler way to call <code>XSLoader::load()</code> with no arguments at all does not work on Perl 5.8.4 and 5.8.5.</p> <h1 id="BUGS">BUGS</h1> <p>Please report any bugs or feature requests via the perlbug(1) utility.</p> <h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1> <p><a href="/pod/DynaLoader">DynaLoader</a></p> <h1 id="AUTHORS">AUTHORS</h1> <p>Ilya Zakharevich originally extracted <code>XSLoader</code> from <code>DynaLoader</code>.</p> <p>CPAN version is currently maintained by Sébastien Aperghis-Tramoni <sebastien@aperghis.net>.</p> <p>Previous maintainer was Michael G Schwern <schwern@pobox.com>.</p> <h1 id="COPYRIGHT-&-LICENSE"><a id="COPYRIGHT"></a><a id="COPYRIGHT-LICENSE"></a>COPYRIGHT & LICENSE</h1> <p>Copyright (C) 1990-2011 by Larry Wall and others.</p> <p>This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p></div> <div id="metacpan_install-instructions-dialog" class="modal fade"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button> <h4 class="modal-title">Module Install Instructions</h4> </div> <div class="modal-body"> <p>To install XSLoader, copy and paste the appropriate command in to your terminal.</p> <p><a href="/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p> <pre><code>cpanm XSLoader</code></pre> <p><a href="/pod/CPAN">CPAN shell</a></p> <pre><code>perl -MCPAN -e shell install XSLoader</code></pre> <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p> </div> <div class="modal-footer"> <a href="#" data-dismiss="modal" class="btn">Close</a> </div> </div> </div> </div> </main> <div class="content-pagination"> </div> </div> <footer class="footer"> <div class="footer-container"> <div class="footer-social"> <div class="footer-link footer-logo"> <a href="/"> <img src="/static/images/metacpan-logo.svg" alt="MetaCPAN" /> </a> </div> <a class="footer-social-link" href="https://github.com/metacpan"> <i class="fab fa-github-square"></i> </a> <a class="footer-social-link" href="https://fosstodon.org/@metacpan"> <i class="fab fa-mastodon"></i> </a> </div> <div class="footer-links"> <div class="footer-link"> <a href="/about">About</a> </div> <div class="footer-link"> <a href="/about/sponsors">Sponsor</a> </div> <div class="footer-link"> <a href="https://grep.metacpan.org">grep::cpan</a> </div> <div class="footer-link"> <a href="/recent">Recent</a> </div> <div class="footer-link"> <a href="/about/faq">FAQ</a> </div> <div class="footer-link"> <a href="/tools">Tools</a> </div> <div class="footer-link"> <a href="https://fastapi.metacpan.org/">API</a> </div> <div class="footer-link"> <a href="https://www.perl.org/">Perl.org</a> </div> </div> <div class="footer-sponsors"> <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener"> <img class="footer-sponsor-bytemark" src="/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo"> </a> <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener"> <img class="footer-sponsor-liquidweb" src="/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo"> </a> <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener"> <img class="footer-sponsor-deriv" src="/static/images/sponsors/deriv.svg" alt="Deriv logo"> </a> <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener"> <img class="footer-sponsor-geocode" src="/static/images/sponsors/geocodelogo.svg" alt="Geocode logo"> </a> <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener"> <img class="footer-sponsor-fastly" src="/static/images/sponsors/fastly_logo.svg" alt="Fastly logo"> </a> <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener"> <img class="footer-sponsor-opencage" src="/static/images/sponsors/open-cage.svg" alt="OpenCage logo"> </a> <!-- Added 2024-07-22 --> <a class="footer-sponsor-link" target="_blank" href="https://www.elastic.co/" rel="noopener"> <img class="footer-sponsor-elastic" src="/static/images/sponsors/elastic.svg" alt="Elastic logo"> </a> <!-- Added 2024-07-22 --> <a class="footer-sponsor-link" target="_blank" href="https://route4me.com/" rel="noopener"> <img class="footer-sponsor-route4me" src="/static/images/sponsors/route4me.png" alt="Route4Me logo"> </a> </div> </div> </footer> <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <button type="button" class="close" data-dismiss="modal">×</button> <h4 class="modal-title">Keyboard Shortcuts</h4> </div> <div class="modal-body row"> <div class="col-md-6"> <table class="table keyboard-shortcuts"> <thead> <tr> <th></th> <th>Global</th> </tr> </thead> <tbody> <tr> <td class="keys"> <kbd>s</kbd> </td> <td>Focus search bar</td> </tr> <tr> <td class="keys"> <kbd>?</kbd> </td> <td>Bring up this help dialog</td> </tr> </tbody> </table> <table class="table keyboard-shortcuts"> <thead> <tr> <th></th> <th>GitHub</th> </tr> </thead> <tbody> <tr> <td class="keys"> <kbd>g</kbd> <kbd>p</kbd> </td> <td>Go to pull requests</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>i</kbd> </td> <td>go to github issues (only if github is preferred repository)</td> </tr> </tbody> </table> </div> <div class="col-md-6"> <table class="table keyboard-shortcuts"> <thead> <tr> <th></th> <th>POD</th> </tr> </thead> <tbody> <tr> <td class="keys"> <kbd>g</kbd> <kbd>a</kbd> </td> <td>Go to author</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>c</kbd> </td> <td>Go to changes</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>i</kbd> </td> <td>Go to issues</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>d</kbd> </td> <td>Go to dist</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>r</kbd> </td> <td>Go to repository/SCM</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>s</kbd> </td> <td>Go to source</td> </tr> <tr> <td class="keys"> <kbd>g</kbd> <kbd>b</kbd> </td> <td>Go to file browse</td> </tr> </tbody> </table> </div> <div class="col-md-12"> <table class="table keyboard-shortcuts"> <thead> <tr> <th></th> <th>Search terms</th> </tr> </thead> <tbody> <tr> <td><em>module:</em> (e.g. <a href="/search?q=module%3APlugin">module:Plugin</a>)</td> </tr> <tr> <td><em>distribution:</em> (e.g. <a href="/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td> </tr> <tr> <td><em>author:</em> (e.g. <a href="/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td> </tr> <tr> <td><em>version:</em> (e.g. <a href="/search?q=version%3A1.00">version:1.00</a>)</td> </tr> </tbody> </table> </div> </div> <div class="modal-footer"></div> </div> </div> </div> </body> </html>