local-lib5/man/man3/XSLoader.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XSLoader 3"
 127 .TH XSLoader 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XSLoader \- Dynamically load C libraries into Perl code
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 Version 0.10
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 .Vb 2
 140 \&    package YourPackage;
 141 \&    use XSLoader;
 142 \&
 143 \&    XSLoader::load \*(AqYourPackage\*(Aq, $YourPackage::VERSION;
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 This module defines a standard \fIsimplified\fR interface to the dynamic
 148 linking mechanisms available on many platforms.  Its primary purpose is
 149 to implement cheap automatic dynamic loading of Perl modules.
 150 .PP
 151 For a more complicated interface, see DynaLoader.  Many (most)
 152 features of \f(CW\*(C`DynaLoader\*(C'\fR are not implemented in \f(CW\*(C`XSLoader\*(C'\fR, like for
 153 example the \f(CW\*(C`dl_load_flags\*(C'\fR, not honored by \f(CW\*(C`XSLoader\*(C'\fR.
 154 .ie n .SS "Migration from ""DynaLoader"""
 155 .el .SS "Migration from \f(CWDynaLoader\fP"
 156 .IX Subsection "Migration from DynaLoader"
 157 A typical module using DynaLoader starts like this:
 158 .PP
 159 .Vb 2
 160 \&    package YourPackage;
 161 \&    require DynaLoader;
 162 \&
 163 \&    our @ISA = qw( OnePackage OtherPackage DynaLoader );
 164 \&    our $VERSION = \*(Aq0.01\*(Aq;
 165 \&    bootstrap YourPackage $VERSION;
 166 .Ve
 167 .PP
 168 Change this to
 169 .PP
 170 .Vb 2
 171 \&    package YourPackage;
 172 \&    use XSLoader;
 173 \&
 174 \&    our @ISA = qw( OnePackage OtherPackage );
 175 \&    our $VERSION = \*(Aq0.01\*(Aq;
 176 \&    XSLoader::load \*(AqYourPackage\*(Aq, $VERSION;
 177 .Ve
 178 .PP
 179 In other words: replace \f(CW\*(C`require DynaLoader\*(C'\fR by \f(CW\*(C`use XSLoader\*(C'\fR, remove
 180 \&\f(CW\*(C`DynaLoader\*(C'\fR from \f(CW@ISA\fR, change \f(CW\*(C`bootstrap\*(C'\fR by \f(CW\*(C`XSLoader::load\*(C'\fR.  Do not
 181 forget to quote the name of your package on the \f(CW\*(C`XSLoader::load\*(C'\fR line,
 182 and add comma (\f(CW\*(C`,\*(C'\fR) before the arguments (\f(CW$VERSION\fR above).
 183 .PP
 184 Of course, if \f(CW@ISA\fR contained only \f(CW\*(C`DynaLoader\*(C'\fR, there is no need to have
 185 the \f(CW@ISA\fR assignment at all; moreover, if instead of \f(CW\*(C`our\*(C'\fR one uses the
 186 more backward-compatible
 187 .PP
 188 .Vb 1
 189 \&    use vars qw($VERSION @ISA);
 190 .Ve
 191 .PP
 192 one can remove this reference to \f(CW@ISA\fR together with the \f(CW@ISA\fR assignment.
 193 .PP
 194 If no \f(CW$VERSION\fR was specified on the \f(CW\*(C`bootstrap\*(C'\fR line, the last line becomes
 195 .PP
 196 .Vb 1
 197 \&    XSLoader::load \*(AqYourPackage\*(Aq;
 198 .Ve
 199 .SS "Backward compatible boilerplate"
 200 .IX Subsection "Backward compatible boilerplate"
 201 If you want to have your cake and eat it too, you need a more complicated
 202 boilerplate.
 203 .PP
 204 .Vb 2
 205 \&    package YourPackage;
 206 \&    use vars qw($VERSION @ISA);
 207 \&
 208 \&    @ISA = qw( OnePackage OtherPackage );
 209 \&    $VERSION = \*(Aq0.01\*(Aq;
 210 \&    eval {
 211 \&       require XSLoader;
 212 \&       XSLoader::load(\*(AqYourPackage\*(Aq, $VERSION);
 213 \&       1;
 214 \&    } or do {
 215 \&       require DynaLoader;
 216 \&       push @ISA, \*(AqDynaLoader\*(Aq;
 217 \&       bootstrap YourPackage $VERSION;
 218 \&    };
 219 .Ve
 220 .PP
 221 The parentheses about \f(CW\*(C`XSLoader::load()\*(C'\fR arguments are needed since we replaced
 222 \&\f(CW\*(C`use XSLoader\*(C'\fR by \f(CW\*(C`require\*(C'\fR, so the compiler does not know that a function
 223 \&\f(CW\*(C`XSLoader::load()\*(C'\fR is present.
 224 .PP
 225 This boilerplate uses the low-overhead \f(CW\*(C`XSLoader\*(C'\fR if present; if used with
 226 an antic Perl which has no \f(CW\*(C`XSLoader\*(C'\fR, it falls back to using \f(CW\*(C`DynaLoader\*(C'\fR.
 227 .SH "Order of initialization: early \fIload()\fP"
 228 .IX Header "Order of initialization: early load()"
 229 \&\fISkip this section if the \s-1XSUB\s0 functions are supposed to be called from other
 230 modules only; read it only if you call your XSUBs from the code in your module,
 231 or have a \f(CI\*(C`BOOT:\*(C'\fI section in your \s-1XS\s0 file (see \*(L"The \s-1BOOT:\s0 Keyword\*(R" in perlxs).
 232 What is described here is equally applicable to the DynaLoader
 233 interface.\fR
 234 .PP
 235 A sufficiently complicated module using \s-1XS\s0 would have both Perl code (defined
 236 in \fIYourPackage.pm\fR) and \s-1XS\s0 code (defined in \fIYourPackage.xs\fR).  If this
 237 Perl code makes calls into this \s-1XS\s0 code, and/or this \s-1XS\s0 code makes calls to
 238 the Perl code, one should be careful with the order of initialization.
 239 .PP
 240 The call to \f(CW\*(C`XSLoader::load()\*(C'\fR (or \f(CW\*(C`bootstrap()\*(C'\fR) has three side effects:
 241 .IP "\(bu" 4
 242 if \f(CW$VERSION\fR was specified, a sanity check is done to ensure that the
 243 versions of the \fI.pm\fR and the (compiled) \fI.xs\fR parts are compatible;
 244 .IP "\(bu" 4
 245 the XSUBs are made accessible from Perl;
 246 .IP "\(bu" 4
 247 if a \f(CW\*(C`BOOT:\*(C'\fR section was present in the \fI.xs\fR file, the code there is called.
 248 .PP
 249 Consequently, if the code in the \fI.pm\fR file makes calls to these XSUBs, it is
 250 convenient to have XSUBs installed before the Perl code is defined; for
 251 example, this makes prototypes for XSUBs visible to this Perl code.
 252 Alternatively, if the \f(CW\*(C`BOOT:\*(C'\fR section makes calls to Perl functions (or
 253 uses Perl variables) defined in the \fI.pm\fR file, they must be defined prior to
 254 the call to \f(CW\*(C`XSLoader::load()\*(C'\fR (or \f(CW\*(C`bootstrap()\*(C'\fR).
 255 .PP
 256 The first situation being much more frequent, it makes sense to rewrite the
 257 boilerplate as
 258 .PP
 259 .Vb 3
 260 \&    package YourPackage;
 261 \&    use XSLoader;
 262 \&    use vars qw($VERSION @ISA);
 263 \&
 264 \&    BEGIN {
 265 \&       @ISA = qw( OnePackage OtherPackage );
 266 \&       $VERSION = \*(Aq0.01\*(Aq;
 267 \&
 268 \&       # Put Perl code used in the BOOT: section here
 269 \&
 270 \&       XSLoader::load \*(AqYourPackage\*(Aq, $VERSION;
 271 \&    }
 272 \&
 273 \&    # Put Perl code making calls into XSUBs here
 274 .Ve
 275 .SS "The most hairy case"
 276 .IX Subsection "The most hairy case"
 277 If the interdependence of your \f(CW\*(C`BOOT:\*(C'\fR section and Perl code is
 278 more complicated than this (e.g., the \f(CW\*(C`BOOT:\*(C'\fR section makes calls to Perl
 279 functions which make calls to XSUBs with prototypes), get rid of the \f(CW\*(C`BOOT:\*(C'\fR
 280 section altogether.  Replace it with a function \f(CW\*(C`onBOOT()\*(C'\fR, and call it like
 281 this:
 282 .PP
 283 .Vb 3
 284 \&    package YourPackage;
 285 \&    use XSLoader;
 286 \&    use vars qw($VERSION @ISA);
 287 \&
 288 \&    BEGIN {
 289 \&       @ISA = qw( OnePackage OtherPackage );
 290 \&       $VERSION = \*(Aq0.01\*(Aq;
 291 \&       XSLoader::load \*(AqYourPackage\*(Aq, $VERSION;
 292 \&    }
 293 \&
 294 \&    # Put Perl code used in onBOOT() function here; calls to XSUBs are
 295 \&    # prototype\-checked.
 296 \&
 297 \&    onBOOT;
 298 \&
 299 \&    # Put Perl initialization code assuming that XS is initialized here
 300 .Ve
 301 .SH "DIAGNOSTICS"
 302 .IX Header "DIAGNOSTICS"
 303 .ie n .IP """Can\*(Aqt find \*(Aq%s\*(Aq symbol in %s""" 4
 304 .el .IP "\f(CWCan\*(Aqt find \*(Aq%s\*(Aq symbol in %s\fR" 4
 305 .IX Item "Cant find %s symbol in %s"
 306 \&\fB(F)\fR The bootstrap symbol could not be found in the extension module.
 307 .ie n .IP """Can\*(Aqt load \*(Aq%s\*(Aq for module %s: %s""" 4
 308 .el .IP "\f(CWCan\*(Aqt load \*(Aq%s\*(Aq for module %s: %s\fR" 4
 309 .IX Item "Cant load %s for module %s: %s"
 310 \&\fB(F)\fR The loading or initialisation of the extension module failed.
 311 The detailed error follows.
 312 .ie n .IP """Undefined symbols present after loading %s: %s""" 4
 313 .el .IP "\f(CWUndefined symbols present after loading %s: %s\fR" 4
 314 .IX Item "Undefined symbols present after loading %s: %s"
 315 \&\fB(W)\fR As the message says, some symbols stay undefined although the
 316 extension module was correctly loaded and initialised. The list of undefined
 317 symbols follows.
 318 .ie n .IP """XSLoader::load(\*(AqYour::Module\*(Aq, $Your::Module::VERSION)""" 4
 319 .el .IP "\f(CWXSLoader::load(\*(AqYour::Module\*(Aq, $Your::Module::VERSION)\fR" 4
 320 .IX Item "XSLoader::load(Your::Module, $Your::Module::VERSION)"
 321 \&\fB(F)\fR You tried to invoke \f(CW\*(C`load()\*(C'\fR without any argument. You must supply
 322 a module name, and optionally its version.
 323 .SH "LIMITATIONS"
 324 .IX Header "LIMITATIONS"
 325 To reduce the overhead as much as possible, only one possible location
 326 is checked to find the extension \s-1DLL\s0 (this location is where \f(CW\*(C`make install\*(C'\fR
 327 would put the \s-1DLL\s0).  If not found, the search for the \s-1DLL\s0 is transparently
 328 delegated to \f(CW\*(C`DynaLoader\*(C'\fR, which looks for the \s-1DLL\s0 along the \f(CW@INC\fR list.
 329 .PP
 330 In particular, this is applicable to the structure of \f(CW@INC\fR used for testing
 331 not-yet-installed extensions.  This means that running uninstalled extensions
 332 may have much more overhead than running the same extensions after
 333 \&\f(CW\*(C`make install\*(C'\fR.
 334 .SH "BUGS"
 335 .IX Header "BUGS"
 336 Please report any bugs or feature requests via the \fIperlbug\fR\|(1) utility.
 337 .SH "SEE ALSO"
 338 .IX Header "SEE ALSO"
 339 DynaLoader
 340 .SH "AUTHORS"
 341 .IX Header "AUTHORS"
 342 Ilya Zakharevich originally extracted \f(CW\*(C`XSLoader\*(C'\fR from \f(CW\*(C`DynaLoader\*(C'\fR.
 343 .PP
 344 \&\s-1CPAN\s0 version is currently maintained by Se\*'bastien Aperghis-Tramoni
 345 <sebastien@aperghis.net>.
 346 .PP
 347 Previous maintainer was Michael G Schwern <schwern@pobox.com>.
 348 .SH "COPYRIGHT & LICENSE"
 349 .IX Header "COPYRIGHT & LICENSE"
 350 Copyright (C) 1990\-2007 by Larry Wall and others.
 351 .PP
 352 This program is free software; you can redistribute it and/or modify
 353 it under the same terms as Perl itself.