Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Embed.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 "ExtUtils::Embed 3perl"
58 .TH ExtUtils::Embed 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 ExtUtils::Embed \- Utilities for embedding Perl in C/C++ applications
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 3
68 \& perl \-MExtUtils::Embed \-e xsinit
69 \& perl \-MExtUtils::Embed \-e ccopts
70 \& perl \-MExtUtils::Embed \-e ldopts
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 \&\f(CW\*(C`ExtUtils::Embed\*(C'\fR provides utility functions for embedding a Perl interpreter
75 and extensions in your C/C++ applications.
76 Typically, an application \fIMakefile\fR will invoke \f(CW\*(C`ExtUtils::Embed\*(C'\fR
77 functions while building your application.
78 .PP
79 Note that on Debian systems the \fBlibperl-dev\fR package is required for
80 compiling applications which embed an interpreter.
81 .ie n .SH @EXPORT
82 .el .SH \f(CW@EXPORT\fP
83 .IX Header "@EXPORT"
84 \&\f(CW\*(C`ExtUtils::Embed\*(C'\fR exports the following functions:
85 .PP
86 \&\fBxsinit()\fR, \fBldopts()\fR, \fBccopts()\fR, \fBperl_inc()\fR, \fBccflags()\fR,
87 \&\fBccdlflags()\fR, \fBxsi_header()\fR, \fBxsi_protos()\fR, \fBxsi_body()\fR
88 .SH FUNCTIONS
89 .IX Header "FUNCTIONS"
90 .IP \fBxsinit()\fR 4
91 .IX Item "xsinit()"
92 Generate C/C++ code for the XS initializer function.
93 .Sp
94 When invoked as \f(CW\`perl \-MExtUtils::Embed \-e xsinit \-\-\`\fR
95 the following options are recognized:
96 .Sp
97 \&\fB\-o\fR <output filename> (Defaults to \fBperlxsi.c\fR)
98 .Sp
99 \&\fB\-o STDOUT\fR will print to STDOUT.
100 .Sp
101 \&\fB\-std\fR (Write code for extensions that are linked with the current Perl.)
102 .Sp
103 Any additional arguments are expected to be names of modules
104 to generate code for.
105 .Sp
106 When invoked with parameters the following are accepted and optional:
107 .Sp
108 \&\f(CW\*(C`xsinit($filename,$std,[@modules])\*(C'\fR
109 .Sp
110 Where,
111 .Sp
112 \&\fR\f(CB$filename\fR\fB\fR is equivalent to the \fB\-o\fR option.
113 .Sp
114 \&\fR\f(CB$std\fR\fB\fR is boolean, equivalent to the \fB\-std\fR option.
115 .Sp
116 \&\fB[@modules]\fR is an array ref, same as additional arguments mentioned above.
117 .IP Examples 4
118 .IX Item "Examples"
119 .Vb 1
120 \& perl \-MExtUtils::Embed \-e xsinit \-\- \-o xsinit.c Socket
121 .Ve
122 .Sp
123 This will generate code with an \f(CW\*(C`xs_init\*(C'\fR function that glues the perl \f(CW\*(C`Socket::bootstrap\*(C'\fR function
124 to the C \f(CW\*(C`boot_Socket\*(C'\fR function and writes it to a file named \fIxsinit.c\fR.
125 .Sp
126 Note that DynaLoader is a special case where it must call \f(CW\*(C`boot_DynaLoader\*(C'\fR directly.
127 .Sp
128 .Vb 1
129 \& perl \-MExtUtils::Embed \-e xsinit
130 .Ve
131 .Sp
132 This will generate code for linking with \f(CW\*(C`DynaLoader\*(C'\fR and
133 each static extension found in \f(CW$Config{static_ext}\fR.
134 The code is written to the default file name \fIperlxsi.c\fR.
135 .Sp
136 .Vb 2
137 \& perl \-MExtUtils::Embed \-e xsinit \-\- \-o xsinit.c \e
138 \& \-std DBI DBD::Oracle
139 .Ve
140 .Sp
141 Here, code is written for all the currently linked extensions along with code
142 for \f(CW\*(C`DBI\*(C'\fR and \f(CW\*(C`DBD::Oracle\*(C'\fR.
143 .Sp
144 If you have a working \f(CW\*(C`DynaLoader\*(C'\fR then there is rarely any need to statically link in any
145 other extensions.
146 .IP \fBldopts()\fR 4
147 .IX Item "ldopts()"
148 Output arguments for linking the Perl library and extensions to your
149 application.
150 .Sp
151 When invoked as \f(CW\`perl \-MExtUtils::Embed \-e ldopts \-\-\`\fR
152 the following options are recognized:
153 .Sp
154 \&\fB\-std\fR
155 .Sp
156 Output arguments for linking the Perl library and any extensions linked
157 with the current Perl.
158 .Sp
159 \&\fB\-I\fR <path1:path2>
160 .Sp
161 Search path for ModuleName.a archives.
162 Default path is \f(CW@INC\fR.
163 Library archives are expected to be found as
164 \&\fI/some/path/auto/ModuleName/ModuleName.a\fR
165 For example, when looking for \fISocket.a\fR relative to a search path,
166 we should find \fIauto/Socket/Socket.a\fR
167 .Sp
168 When looking for \f(CW\*(C`DBD::Oracle\*(C'\fR relative to a search path,
169 we should find \fIauto/DBD/Oracle/Oracle.a\fR
170 .Sp
171 Keep in mind that you can always supply \fI/my/own/path/ModuleName.a\fR
172 as an additional linker argument.
173 .Sp
174 \&\fB\-\-\fR <list of linker args>
175 .Sp
176 Additional linker arguments to be considered.
177 .Sp
178 Any additional arguments found before the \fB\-\-\fR token
179 are expected to be names of modules to generate code for.
180 .Sp
181 When invoked with parameters the following are accepted and optional:
182 .Sp
183 \&\f(CW\*(C`ldopts($std,[@modules],[@link_args],$path)\*(C'\fR
184 .Sp
185 Where:
186 .Sp
187 \&\fR\f(CB$std\fR\fB\fR is boolean, equivalent to the \fB\-std\fR option.
188 .Sp
189 \&\fB[@modules]\fR is equivalent to additional arguments found before the \fB\-\-\fR token.
190 .Sp
191 \&\fB[@link_args]\fR is equivalent to arguments found after the \fB\-\-\fR token.
192 .Sp
193 \&\fR\f(CB$path\fR\fB\fR is equivalent to the \fB\-I\fR option.
194 .Sp
195 In addition, when ldopts is called with parameters, it will return the argument string
196 rather than print it to STDOUT.
197 .IP Examples 4
198 .IX Item "Examples"
199 .Vb 1
200 \& perl \-MExtUtils::Embed \-e ldopts
201 .Ve
202 .Sp
203 This will print arguments for linking with \f(CW\*(C`libperl\*(C'\fR and
204 extensions found in \f(CW$Config{static_ext}\fR. This includes libraries
205 found in \f(CW$Config{libs}\fR and the first ModuleName.a library
206 for each extension that is found by searching \f(CW@INC\fR or the path
207 specified by the \fB\-I\fR option.
208 In addition, when ModuleName.a is found, additional linker arguments
209 are picked up from the \fIextralibs.ld\fR file in the same directory.
210 .Sp
211 .Vb 1
212 \& perl \-MExtUtils::Embed \-e ldopts \-\- \-std Socket
213 .Ve
214 .Sp
215 This will do the same as the above example, along with printing additional
216 arguments for linking with the \f(CW\*(C`Socket\*(C'\fR extension.
217 .Sp
218 .Vb 2
219 \& perl \-MExtUtils::Embed \-e ldopts \-\- \-std Msql \-\- \e
220 \& \-L/usr/msql/lib \-lmsql
221 .Ve
222 .Sp
223 Any arguments after the second '\-\-' token are additional linker
224 arguments that will be examined for potential conflict. If there is no
225 conflict, the additional arguments will be part of the output.
226 .IP \fBperl_inc()\fR 4
227 .IX Item "perl_inc()"
228 For including perl header files this function simply prints:
229 .Sp
230 .Vb 1
231 \& \-I$Config{archlibexp}/CORE
232 .Ve
233 .Sp
234 So, rather than having to say:
235 .Sp
236 .Vb 1
237 \& perl \-MConfig \-e \*(Aqprint "\-I$Config{archlibexp}/CORE"\*(Aq
238 .Ve
239 .Sp
240 Just say:
241 .Sp
242 .Vb 1
243 \& perl \-MExtUtils::Embed \-e perl_inc
244 .Ve
245 .IP "\fBccflags()\fR, \fBccdlflags()\fR" 4
246 .IX Item "ccflags(), ccdlflags()"
247 These functions simply print \f(CW$Config\fR{ccflags} and \f(CW$Config\fR{ccdlflags}
248 .IP \fBccopts()\fR 4
249 .IX Item "ccopts()"
250 This function combines \f(CWperl_inc()\fR, \f(CWccflags()\fR and \f(CWccdlflags()\fR into one.
251 .IP \fBxsi_header()\fR 4
252 .IX Item "xsi_header()"
253 This function simply returns a string defining the same \f(CW\*(C`EXTERN_C\*(C'\fR macro as
254 \&\fIperlmain.c\fR along with #including \fIperl.h\fR and \fIEXTERN.h\fR.
255 .IP xsi_protos(@modules) 4
256 .IX Item "xsi_protos(@modules)"
257 This function returns a string of \f(CW\*(C`boot_$ModuleName\*(C'\fR prototypes for each \f(CW@modules\fR.
258 .IP xsi_body(@modules) 4
259 .IX Item "xsi_body(@modules)"
260 This function returns a string of calls to \f(CWnewXS()\fR that glue the module \fIbootstrap\fR
261 function to \fIboot_ModuleName\fR for each \f(CW@modules\fR.
262 .Sp
263 \&\f(CWxsinit()\fR uses the xsi_* functions to generate most of its code.
264 .SH EXAMPLES
265 .IX Header "EXAMPLES"
266 For examples on how to use \f(CW\*(C`ExtUtils::Embed\*(C'\fR for building C/C++ applications
267 with embedded perl, see perlembed.
268 .SH "SEE ALSO"
269 .IX Header "SEE ALSO"
270 perlembed
271 .SH AUTHOR
272 .IX Header "AUTHOR"
273 Doug MacEachern <\f(CW\*(C`[email protected]\*(C'\fR>
274 .PP
275 Based on ideas from Tim Bunce <\f(CW\*(C`[email protected]\*(C'\fR> and
276 \&\fIminimod.pl\fR by Andreas Koenig <\f(CW\*(C`[email protected]\-berlin.de\*(C'\fR> and Tim Bunce.