ExtUtils::Embed(3pm)

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 inter‐
15       preter and extensions in your C/C++ applications.  Typically, an appli‐
16       cation Makefile will invoke ExtUtils::Embed functions while building
17       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 following
30           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 and
61           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 static
69           extension found in $Config{static_ext}.  The code is written to the
70           default file name perlxsi.c.
71
72            perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
73
74           Here, code is written for all the currently linked extensions along
75           with code for DBI and DBD::Oracle.
76
77           If you have a working DynaLoader then there is rarely any need to
78           statically link in any other extensions.
79
80       ldopts()
81           Output arguments for linking the Perl library and extensions to
82           your application.
83
84           When invoked as `perl -MExtUtils::Embed -e ldopts --` the following
85           options are recognized:
86
87           -std
88
89           Output arguments for linking the Perl library and any extensions
90           linked with the current Perl.
91
92           -I <path1:path2>
93
94           Search path for ModuleName.a archives.  Default path is @INC.
95           Library archives are expected to be found as /some/path/auto/Modu‐
96           leName/ModuleName.a For example, when looking for Socket.a relative
97           to a search path, we should find auto/Socket/Socket.a
98
99           When looking for DBD::Oracle relative to a search path, we should
100           find auto/DBD/Oracle/Oracle.a
101
102           Keep in mind that you can always supply /my/own/path/ModuleName.a
103           as an additional linker argument.
104
105           --  <list of linker args>
106
107           Additional linker arguments to be considered.
108
109           Any additional arguments found before the -- token are expected to
110           be names of modules to generate code for.
111
112           When invoked with parameters the following are accepted and
113           optional:
114
115           "ldopts($std,[@modules],[@link_args],$path)"
116
117           Where:
118
119           $std is boolean, equivalent to the -std option.
120
121           [@modules] is equivalent to additional arguments found before the
122           -- token.
123
124           [@link_args] is equivalent to arguments found after the -- token.
125
126           $path is equivalent to the -I option.
127
128           In addition, when ldopts is called with parameters, it will return
129           the argument string rather than print it to STDOUT.
130
131       Examples
132            perl -MExtUtils::Embed -e ldopts
133
134           This will print arguments for linking with libperl.a, DynaLoader
135           and extensions found in $Config{static_ext}.  This includes
136           libraries found in $Config{libs} and the first ModuleName.a library
137           for each extension that is found by searching @INC or the path
138           specified by the -I option.  In addition, when ModuleName.a is
139           found, additional linker arguments are picked up from the extral‐
140           ibs.ld file in the same directory.
141
142            perl -MExtUtils::Embed -e ldopts -- -std Socket
143
144           This will do the same as the above example, along with printing
145           additional arguments for linking with the Socket extension.
146
147            perl -MExtUtils::Embed -e ldopts -- DynaLoader
148
149           This will print arguments for linking with just the DynaLoader
150           extension and libperl.a.
151
152            perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
153
154           Any arguments after the second '--' token are additional linker
155           arguments that will be examined for potential conflict.  If there
156           is no conflict, the additional arguments will be part of the out‐
157           put.
158
159       perl_inc()
160           For including perl header files this function simply prints:
161
162            -I$Config{archlibexp}/CORE
163
164           So, rather than having to say:
165
166            perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
167
168           Just say:
169
170            perl -MExtUtils::Embed -e perl_inc
171
172       ccflags(), ccdlflags()
173           These functions simply print $Config{ccflags} and $Con‐
174           fig{ccdlflags}
175
176       ccopts()
177           This function combines perl_inc(), ccflags() and ccdlflags() into
178           one.
179
180       xsi_header()
181           This function simply returns a string defining the same EXTERN_C
182           macro as perlmain.c along with #including perl.h and EXTERN.h.
183
184       xsi_protos(@modules)
185           This function returns a string of boot_$ModuleName prototypes for
186           each @modules.
187
188       xsi_body(@modules)
189           This function returns a string of calls to newXS() that glue the
190           module bootstrap function to boot_ModuleName for each @modules.
191
192           xsinit() uses the xsi_* functions to generate most of its code.
193

EXAMPLES

195       For examples on how to use ExtUtils::Embed for building C/C++ applica‐
196       tions with embedded perl, see perlembed.
197

AUTHOR

202       Doug MacEachern <dougm@osf.org>
203
204       Based on ideas from Tim Bunce <Tim.Bunce@ig.co.uk> and minimod.pl by
205       Andreas Koenig <k@anna.in-berlin.de> and Tim Bunce.
206
207
208
209perl v5.8.8                       2001-09-21              ExtUtils::Embed(3pm)