1ExtUtils::Embed(3pm)   Perl Programmers Reference Guide   ExtUtils::Embed(3pm)
2
3
4

NAME

6       ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
7

SYNOPSIS

9        perl -MExtUtils::Embed -e xsinit
10        perl -MExtUtils::Embed -e ccopts
11        perl -MExtUtils::Embed -e ldopts
12

DESCRIPTION

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

@EXPORT

20       "ExtUtils::Embed" exports the following functions:
21
22       xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(), ccdlflags(),
23       xsi_header(), xsi_protos(), xsi_body()
24

FUNCTIONS

26       xsinit()
27           Generate C/C++ code for the XS initializer function.
28
29           When invoked as "`perl -MExtUtils::Embed -e xsinit --`" the
30           following options are recognized:
31
32           -o <output filename> (Defaults to perlxsi.c)
33
34           -o STDOUT will print to STDOUT.
35
36           -std (Write code for extensions that are linked with the current
37           Perl.)
38
39           Any additional arguments are expected to be names of modules to
40           generate code for.
41
42           When invoked with parameters the following are accepted and
43           optional:
44
45           "xsinit($filename,$std,[@modules])"
46
47           Where,
48
49           $filename is equivalent to the -o option.
50
51           $std is boolean, equivalent to the -std option.
52
53           [@modules] is an array ref, same as additional arguments mentioned
54           above.
55
56       Examples
57            perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
58
59           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
63           Note that DynaLoader is a special case where it must call
64           "boot_DynaLoader" directly.
65
66            perl -MExtUtils::Embed -e xsinit
67
68           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
72            perl -MExtUtils::Embed -e xsinit -- -o xsinit.c \
73                                       -std DBI DBD::Oracle
74
75           Here, code is written for all the currently linked extensions along
76           with code for "DBI" and "DBD::Oracle".
77
78           If you have a working "DynaLoader" then there is rarely any need to
79           statically link in any other extensions.
80
81       ldopts()
82           Output arguments for linking the Perl library and extensions to
83           your application.
84
85           When invoked as "`perl -MExtUtils::Embed -e ldopts --`" the
86           following options are recognized:
87
88           -std
89
90           Output arguments for linking the Perl library and any extensions
91           linked with the current Perl.
92
93           -I <path1:path2>
94
95           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
101           When looking for "DBD::Oracle" relative to a search path, we should
102           find auto/DBD/Oracle/Oracle.a
103
104           Keep in mind that you can always supply /my/own/path/ModuleName.a
105           as an additional linker argument.
106
107           --  <list of linker args>
108
109           Additional linker arguments to be considered.
110
111           Any additional arguments found before the -- token are expected to
112           be names of modules to generate code for.
113
114           When invoked with parameters the following are accepted and
115           optional:
116
117           "ldopts($std,[@modules],[@link_args],$path)"
118
119           Where:
120
121           $std is boolean, equivalent to the -std option.
122
123           [@modules] is equivalent to additional arguments found before the
124           -- token.
125
126           [@link_args] is equivalent to arguments found after the -- token.
127
128           $path is equivalent to the -I option.
129
130           In addition, when ldopts is called with parameters, it will return
131           the argument string rather than print it to STDOUT.
132
133       Examples
134            perl -MExtUtils::Embed -e ldopts
135
136           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
144            perl -MExtUtils::Embed -e ldopts -- -std Socket
145
146           This will do the same as the above example, along with printing
147           additional arguments for linking with the "Socket" extension.
148
149            perl -MExtUtils::Embed -e ldopts -- -std Msql -- \
150                                   -L/usr/msql/lib -lmsql
151
152           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
157       perl_inc()
158           For including perl header files this function simply prints:
159
160            -I$Config{archlibexp}/CORE
161
162           So, rather than having to say:
163
164            perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
165
166           Just say:
167
168            perl -MExtUtils::Embed -e perl_inc
169
170       ccflags(), ccdlflags()
171           These functions simply print $Config{ccflags} and
172           $Config{ccdlflags}
173
174       ccopts()
175           This function combines "perl_inc()", "ccflags()" and "ccdlflags()"
176           into one.
177
178       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
182       xsi_protos(@modules)
183           This function returns a string of "boot_$ModuleName" prototypes for
184           each @modules.
185
186       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
190           "xsinit()" uses the xsi_* functions to generate most of its code.
191

EXAMPLES

193       For examples on how to use "ExtUtils::Embed" for building C/C++
194       applications with embedded perl, see perlembed.
195

SEE ALSO

197       perlembed
198

AUTHOR

200       Doug MacEachern <"dougm@osf.org">
201
202       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.
204
205
206
207perl v5.32.1                      2021-05-31              ExtUtils::Embed(3pm)
Impressum