1ExtUtils::Embed(3pm) Perl Programmers Reference Guide ExtUtils::Embed(3pm)
2
6 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
7
9 perl -MExtUtils::Embed -e xsinit
10 perl -MExtUtils::Embed -e ccopts
11 perl -MExtUtils::Embed -e ldopts
12
14 "ExtUtils::Embed" provides utility functions for embedding a Perl
15 interpreter and extensions in your C/C++ applications. Typically, an
16 application Makefile will invoke "ExtUtils::Embed" functions while
17 building your application.
18
20 "ExtUtils::Embed" exports the following functions:
21 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(), ccdlflags(),
23 xsi_header(), xsi_protos(), xsi_body()
24
26 xsinit()
27 Generate C/C++ code for the XS initializer function.
28 When invoked as `perl -MExtUtils::Embed -e xsinit --` the following
30 options are recognized:
31 -o <output filename> (Defaults to perlxsi.c)
33 -o STDOUT will print to STDOUT.
35 -std (Write code for extensions that are linked with the current
37 Perl.)
38 Any additional arguments are expected to be names of modules to
40 generate code for.
41 When invoked with parameters the following are accepted and
43 optional:
44 "xsinit($filename,$std,[@modules])"
46 Where,
48 $filename is equivalent to the -o option.
50 $std is boolean, equivalent to the -std option.
52 [@modules] is an array ref, same as additional arguments mentioned
54 above.
55 Examples
57 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
58 This will generate code with an "xs_init" function that glues the
60 perl "Socket::bootstrap" function to the C "boot_Socket" function
61 and writes it to a file named xsinit.c.
62 Note that DynaLoader is a special case where it must call
64 "boot_DynaLoader" directly.
65 perl -MExtUtils::Embed -e xsinit
67 This will generate code for linking with "DynaLoader" and each
69 static extension found in $Config{static_ext}. The code is written
70 to the default file name perlxsi.c.
71 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c \
73 -std DBI DBD::Oracle
74 Here, code is written for all the currently linked extensions along
76 with code for "DBI" and "DBD::Oracle".
77 If you have a working "DynaLoader" then there is rarely any need to
79 statically link in any other extensions.
80 ldopts()
82 Output arguments for linking the Perl library and extensions to
83 your application.
84 When invoked as `perl -MExtUtils::Embed -e ldopts --` the following
86 options are recognized:
87 -std
89 Output arguments for linking the Perl library and any extensions
91 linked with the current Perl.
92 -I <path1:path2>
94 Search path for ModuleName.a archives. Default path is @INC.
96 Library archives are expected to be found as
97 /some/path/auto/ModuleName/ModuleName.a For example, when looking
98 for Socket.a relative to a search path, we should find
99 auto/Socket/Socket.a
100 When looking for "DBD::Oracle" relative to a search path, we should
102 find auto/DBD/Oracle/Oracle.a
103 Keep in mind that you can always supply /my/own/path/ModuleName.a
105 as an additional linker argument.
106 -- <list of linker args>
108 Additional linker arguments to be considered.
110 Any additional arguments found before the -- token are expected to
112 be names of modules to generate code for.
113 When invoked with parameters the following are accepted and
115 optional:
116 "ldopts($std,[@modules],[@link_args],$path)"
118 Where:
120 $std is boolean, equivalent to the -std option.
122 [@modules] is equivalent to additional arguments found before the
124 -- token.
125 [@link_args] is equivalent to arguments found after the -- token.
127 $path is equivalent to the -I option.
129 In addition, when ldopts is called with parameters, it will return
131 the argument string rather than print it to STDOUT.
132 Examples
134 perl -MExtUtils::Embed -e ldopts
135 This will print arguments for linking with "libperl" and extensions
137 found in $Config{static_ext}. This includes libraries found in
138 $Config{libs} and the first ModuleName.a library for each extension
139 that is found by searching @INC or the path specified by the -I
140 option. In addition, when ModuleName.a is found, additional linker
141 arguments are picked up from the extralibs.ld file in the same
142 directory.
143 perl -MExtUtils::Embed -e ldopts -- -std Socket
145 This will do the same as the above example, along with printing
147 additional arguments for linking with the "Socket" extension.
148 perl -MExtUtils::Embed -e ldopts -- -std Msql -- \
150 -L/usr/msql/lib -lmsql
151 Any arguments after the second '--' token are additional linker
153 arguments that will be examined for potential conflict. If there
154 is no conflict, the additional arguments will be part of the
155 output.
156 perl_inc()
158 For including perl header files this function simply prints:
159 -I$Config{archlibexp}/CORE
161 So, rather than having to say:
163 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
165 Just say:
167 perl -MExtUtils::Embed -e perl_inc
169 ccflags(), ccdlflags()
171 These functions simply print $Config{ccflags} and
172 $Config{ccdlflags}
173 ccopts()
175 This function combines perl_inc(), ccflags() and ccdlflags() into
176 one.
177 xsi_header()
179 This function simply returns a string defining the same "EXTERN_C"
180 macro as perlmain.c along with #including perl.h and EXTERN.h.
181 xsi_protos(@modules)
183 This function returns a string of "boot_$ModuleName" prototypes for
184 each @modules.
185 xsi_body(@modules)
187 This function returns a string of calls to newXS() that glue the
188 module bootstrap function to boot_ModuleName for each @modules.
189 xsinit() uses the xsi_* functions to generate most of its code.
191
193 For examples on how to use "ExtUtils::Embed" for building C/C++
194 applications with embedded perl, see perlembed.
195
197 perlembed
198
200 Doug MacEachern <"dougm@osf.org">
201 Based on ideas from Tim Bunce <"Tim.Bunce@ig.co.uk"> and minimod.pl by
203 Andreas Koenig <"k@anna.in-berlin.de"> and Tim Bunce.
204perl v5.38.2 2023-11-30 ExtUtils::Embed(3pm)