Debian Codegraph @

upstream/debian-unstable/man3/XSLoader.3perl

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