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
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 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
85           following 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
96           /some/path/auto/ModuleName/ModuleName.a For example, when looking
97           for Socket.a relative to a search path, we should find
98           auto/Socket/Socket.a
99
100           When looking for DBD::Oracle relative to a search path, we should
101           find auto/DBD/Oracle/Oracle.a
102
103           Keep in mind that you can always supply /my/own/path/ModuleName.a
104           as an additional linker argument.
105
106           --  <list of linker args>
107
108           Additional linker arguments to be considered.
109
110           Any additional arguments found before the -- token are expected to
111           be names of modules to generate code for.
112
113           When invoked with parameters the following are accepted and
114           optional:
115
116           "ldopts($std,[@modules],[@link_args],$path)"
117
118           Where:
119
120           $std is boolean, equivalent to the -std option.
121
122           [@modules] is equivalent to additional arguments found before the
123           -- token.
124
125           [@link_args] is equivalent to arguments found after the -- token.
126
127           $path is equivalent to the -I option.
128
129           In addition, when ldopts is called with parameters, it will return
130           the argument string rather than print it to STDOUT.
131
132       Examples
133            perl -MExtUtils::Embed -e ldopts
134
135           This will print arguments for linking with libperl and extensions
136           found in $Config{static_ext}.  This includes libraries found in
137           $Config{libs} and the first ModuleName.a library for each extension
138           that is found by searching @INC or the path specified by the -I
139           option.  In addition, when ModuleName.a is found, additional linker
140           arguments are picked up from the extralibs.ld file in the same
141           directory.
142
143            perl -MExtUtils::Embed -e ldopts -- -std Socket
144
145           This will do the same as the above example, along with printing
146           additional arguments for linking with the Socket extension.
147
148            perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
149
150           Any arguments after the second '--' token are additional linker
151           arguments that will be examined for potential conflict.  If there
152           is no conflict, the additional arguments will be part of the
153           output.
154
155       perl_inc()
156           For including perl header files this function simply prints:
157
158            -I$Config{archlibexp}/CORE
159
160           So, rather than having to say:
161
162            perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
163
164           Just say:
165
166            perl -MExtUtils::Embed -e perl_inc
167
168       ccflags(), ccdlflags()
169           These functions simply print $Config{ccflags} and
170           $Config{ccdlflags}
171
172       ccopts()
173           This function combines perl_inc(), ccflags() and ccdlflags() into
174           one.
175
176       xsi_header()
177           This function simply returns a string defining the same EXTERN_C
178           macro as perlmain.c along with #including perl.h and EXTERN.h.
179
180       xsi_protos(@modules)
181           This function returns a string of boot_$ModuleName prototypes for
182           each @modules.
183
184       xsi_body(@modules)
185           This function returns a string of calls to newXS() that glue the
186           module bootstrap function to boot_ModuleName for each @modules.
187
188           xsinit() uses the xsi_* functions to generate most of its code.
189

EXAMPLES

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

AUTHOR

198       Doug MacEachern <dougm@osf.org>
199
200       Based on ideas from Tim Bunce <Tim.Bunce@ig.co.uk> and minimod.pl by
201       Andreas Koenig <k@anna.in-berlin.de> and Tim Bunce.
202
203
204
205perl v5.16.3                      2013-03-04              ExtUtils::Embed(3pm)