Debian Codegraph @

upstream/mageia-cauldron/man3pm/XSLoader.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "XSLoader 3pm"
61 .TH XSLoader 3pm 2026-05-26 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 XSLoader \- Dynamically load C libraries into Perl code
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 0.32
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& package YourPackage;
75 \& require XSLoader;
76 \&
77 \& XSLoader::load(_\|_PACKAGE_\|_, $VERSION);
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 This module defines a standard \fIsimplified\fR interface to the dynamic
82 linking mechanisms available on many platforms. Its primary purpose is
83 to implement cheap automatic dynamic loading of Perl modules.
84 .PP
85 For a more complicated interface, see DynaLoader. Many (most)
86 features of \f(CW\*(C`DynaLoader\*(C'\fR are not implemented in \f(CW\*(C`XSLoader\*(C'\fR, like for
87 example the \f(CW\*(C`dl_load_flags\*(C'\fR, not honored by \f(CW\*(C`XSLoader\*(C'\fR.
88 .ie n .SS "Migration from ""DynaLoader"""
89 .el .SS "Migration from \f(CWDynaLoader\fP"
90 .IX Subsection "Migration from DynaLoader"
91 A typical module using DynaLoader starts like this:
92 .PP
93 .Vb 2
94 \& package YourPackage;
95 \& require DynaLoader;
96 \&
97 \& our @ISA = qw( OnePackage OtherPackage DynaLoader );
98 \& our $VERSION = \*(Aq0.01\*(Aq;
99 \& _\|_PACKAGE_\|_\->bootstrap($VERSION);
100 .Ve
101 .PP
102 Change this to
103 .PP
104 .Vb 2
105 \& package YourPackage;
106 \& use XSLoader;
107 \&
108 \& our @ISA = qw( OnePackage OtherPackage );
109 \& our $VERSION = \*(Aq0.01\*(Aq;
110 \& XSLoader::load(_\|_PACKAGE_\|_, $VERSION);
111 .Ve
112 .PP
113 In other words: replace \f(CW\*(C`require DynaLoader\*(C'\fR by \f(CW\*(C`use XSLoader\*(C'\fR, remove
114 \&\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
115 forget to quote the name of your package on the \f(CW\*(C`XSLoader::load\*(C'\fR line,
116 and add comma (\f(CW\*(C`,\*(C'\fR) before the arguments (\f(CW$VERSION\fR above).
117 .PP
118 Of course, if \f(CW@ISA\fR contained only \f(CW\*(C`DynaLoader\*(C'\fR, there is no need to have
119 the \f(CW@ISA\fR assignment at all; moreover, if instead of \f(CW\*(C`our\*(C'\fR one uses the
120 more backward\-compatible
121 .PP
122 .Vb 1
123 \& use vars qw($VERSION @ISA);
124 .Ve
125 .PP
126 one can remove this reference to \f(CW@ISA\fR together with the \f(CW@ISA\fR assignment.
127 .PP
128 If no \f(CW$VERSION\fR was specified on the \f(CW\*(C`bootstrap\*(C'\fR line, the last line becomes
129 .PP
130 .Vb 1
131 \& XSLoader::load(_\|_PACKAGE_\|_);
132 .Ve
133 .PP
134 in which case it can be further simplified to
135 .PP
136 .Vb 1
137 \& XSLoader::load();
138 .Ve
139 .PP
140 as \f(CW\*(C`load\*(C'\fR will use \f(CW\*(C`caller\*(C'\fR to determine the package.
141 .SS "Backward compatible boilerplate"
142 .IX Subsection "Backward compatible boilerplate"
143 If you want to have your cake and eat it too, you need a more complicated
144 boilerplate.
145 .PP
146 .Vb 1
147 \& package YourPackage;
148 \&
149 \& our @ISA = qw( OnePackage OtherPackage );
150 \& our $VERSION = \*(Aq0.01\*(Aq;
151 \& eval {
152 \& require XSLoader;
153 \& XSLoader::load(_\|_PACKAGE_\|_, $VERSION);
154 \& 1;
155 \& } or do {
156 \& require DynaLoader;
157 \& push @ISA, \*(AqDynaLoader\*(Aq;
158 \& _\|_PACKAGE_\|_\->bootstrap($VERSION);
159 \& };
160 .Ve
161 .PP
162 The parentheses about \f(CWXSLoader::load()\fR arguments are needed since we replaced
163 \&\f(CW\*(C`use XSLoader\*(C'\fR by \f(CW\*(C`require\*(C'\fR, so the compiler does not know that a function
164 \&\f(CWXSLoader::load()\fR is present.
165 .PP
166 This boilerplate uses the low\-overhead \f(CW\*(C`XSLoader\*(C'\fR if present; if used with
167 an antique Perl which has no \f(CW\*(C`XSLoader\*(C'\fR, it falls back to using \f(CW\*(C`DynaLoader\*(C'\fR.
168 .SH "Order of initialization: early \fBload()\fP"
169 .IX Header "Order of initialization: early load()"
170 \&\fISkip this section if the XSUB functions are supposed to be called from other
171 modules only; read it only if you call your XSUBs from the code in your module,
172 or have a \fR\f(CI\*(C`BOOT:\*(C'\fR\fI section in your XS file (see "The BOOT: Keyword" in perlxs).
173 What is described here is equally applicable to the DynaLoader
174 interface.\fR
175 .PP
176 A sufficiently complicated module using XS would have both Perl code (defined
177 in \fIYourPackage.pm\fR) and XS code (defined in \fIYourPackage.xs\fR). If this
178 Perl code makes calls into this XS code, and/or this XS code makes calls to
179 the Perl code, one should be careful with the order of initialization.
180 .PP
181 The call to \f(CWXSLoader::load()\fR (or \f(CWbootstrap()\fR) calls the module\*(Aqs
182 bootstrap code. For modules build by \fIxsubpp\fR (nearly all modules) this
183 has three side effects:
184 .IP \(bu 4
185 A sanity check is done to ensure that the versions of the \fI.pm\fR and the
186 (compiled) \fI.xs\fR parts are compatible. If \f(CW$VERSION\fR was specified, this
187 is used for the check. If not specified, it defaults to
188 \&\f(CW\*(C`$XS_VERSION // $VERSION\*(C'\fR (in the module\*(Aqs namespace)
189 .IP \(bu 4
190 the XSUBs are made accessible from Perl
191 .IP \(bu 4
192 if a \f(CW\*(C`BOOT:\*(C'\fR section was present in the \fI.xs\fR file, the code there is called.
193 .PP
194 Consequently, if the code in the \fI.pm\fR file makes calls to these XSUBs, it is
195 convenient to have XSUBs installed before the Perl code is defined; for
196 example, this makes prototypes for XSUBs visible to this Perl code.
197 Alternatively, if the \f(CW\*(C`BOOT:\*(C'\fR section makes calls to Perl functions (or
198 uses Perl variables) defined in the \fI.pm\fR file, they must be defined prior to
199 the call to \f(CWXSLoader::load()\fR (or \f(CWbootstrap()\fR).
200 .PP
201 The first situation being much more frequent, it makes sense to rewrite the
202 boilerplate as
203 .PP
204 .Vb 3
205 \& package YourPackage;
206 \& use XSLoader;
207 \& our ($VERSION, @ISA);
208 \&
209 \& BEGIN {
210 \& @ISA = qw( OnePackage OtherPackage );
211 \& $VERSION = \*(Aq0.01\*(Aq;
212 \&
213 \& # Put Perl code used in the BOOT: section here
214 \&
215 \& XSLoader::load(_\|_PACKAGE_\|_, $VERSION);
216 \& }
217 \&
218 \& # Put Perl code making calls into XSUBs here
219 .Ve
220 .SS "The most hairy case"
221 .IX Subsection "The most hairy case"
222 If the interdependence of your \f(CW\*(C`BOOT:\*(C'\fR section and Perl code is
223 more complicated than this (e.g., the \f(CW\*(C`BOOT:\*(C'\fR section makes calls to Perl
224 functions which make calls to XSUBs with prototypes), get rid of the \f(CW\*(C`BOOT:\*(C'\fR
225 section altogether. Replace it with a function \f(CWonBOOT()\fR, and call it like
226 this:
227 .PP
228 .Vb 3
229 \& package YourPackage;
230 \& use XSLoader;
231 \& our ($VERSION, @ISA);
232 \&
233 \& BEGIN {
234 \& @ISA = qw( OnePackage OtherPackage );
235 \& $VERSION = \*(Aq0.01\*(Aq;
236 \& XSLoader::load(_\|_PACKAGE_\|_, $VERSION);
237 \& }
238 \&
239 \& # Put Perl code used in onBOOT() function here; calls to XSUBs are
240 \& # prototype\-checked.
241 \&
242 \& onBOOT;
243 \&
244 \& # Put Perl initialization code assuming that XS is initialized here
245 .Ve
246 .SH DIAGNOSTICS
247 .IX Header "DIAGNOSTICS"
248 .ie n .IP """Can\*(Aqt find \*(Aq%s\*(Aq symbol in %s""" 4
249 .el .IP "\f(CWCan\*(Aqt find \*(Aq%s\*(Aq symbol in %s\fR" 4
250 .IX Item "Can't find '%s' symbol in %s"
251 \&\fB(F)\fR The bootstrap symbol could not be found in the extension module.
252 .ie n .IP """Can\*(Aqt load \*(Aq%s\*(Aq for module %s: %s""" 4
253 .el .IP "\f(CWCan\*(Aqt load \*(Aq%s\*(Aq for module %s: %s\fR" 4
254 .IX Item "Can't load '%s' for module %s: %s"
255 \&\fB(F)\fR The loading or initialisation of the extension module failed.
256 The detailed error follows.
257 .ie n .IP """Undefined symbols present after loading %s: %s""" 4
258 .el .IP "\f(CWUndefined symbols present after loading %s: %s\fR" 4
259 .IX Item "Undefined symbols present after loading %s: %s"
260 \&\fB(W)\fR As the message says, some symbols stay undefined although the
261 extension module was correctly loaded and initialised. The list of undefined
262 symbols follows.
263 .SH LIMITATIONS
264 .IX Header "LIMITATIONS"
265 To reduce the overhead as much as possible, only one possible location
266 is checked to find the extension DLL (this location is where \f(CW\*(C`make install\*(C'\fR
267 would put the DLL). If not found, the search for the DLL is transparently
268 delegated to \f(CW\*(C`DynaLoader\*(C'\fR, which looks for the DLL along the \f(CW@INC\fR list.
269 .PP
270 In particular, this is applicable to the structure of \f(CW@INC\fR used for testing
271 not\-yet\-installed extensions. This means that running uninstalled extensions
272 may have much more overhead than running the same extensions after
273 \&\f(CW\*(C`make install\*(C'\fR.
274 .SH "KNOWN BUGS"
275 .IX Header "KNOWN BUGS"
276 The new simpler way to call \f(CWXSLoader::load()\fR with no arguments at all
277 does not work on Perl 5.8.4 and 5.8.5.
278 .SH BUGS
279 .IX Header "BUGS"
280 Please report any bugs or feature requests via the \fBperlbug\fR\|(1) utility.
281 .SH "SEE ALSO"
282 .IX Header "SEE ALSO"
283 DynaLoader
284 .SH AUTHORS
285 .IX Header "AUTHORS"
286 Ilya Zakharevich originally extracted \f(CW\*(C`XSLoader\*(C'\fR from \f(CW\*(C`DynaLoader\*(C'\fR.
287 .PP
288 CPAN version is currently maintained by Sébastien Aperghis\-Tramoni
289 <[email protected]>.
290 .PP
291 Previous maintainer was Michael G Schwern <[email protected]>.
292 .SH "COPYRIGHT & LICENSE"
293 .IX Header "COPYRIGHT & LICENSE"
294 Copyright (C) 1990\-2011 by Larry Wall and others.
295 .PP
296 This program is free software; you can redistribute it and/or modify
297 it under the same terms as Perl itself.