1 # $Id: Embed.pm,v 1.2501 $
4 package ExtUtils::Embed;
10 #Only when we need them
11 #require ExtUtils::MakeMaker;
12 #require ExtUtils::Liblist;
14 use vars qw(@ISA @EXPORT $VERSION
15 @Extensions $Verbose $lib_ext
20 $VERSION = sprintf("%d.%02d", q$Revision: 1.2501 $ =~ /(\d+)\.(\d+)/);
21 #for the namespace change
22 $Devel::embed::VERSION = "99.99";
24 sub Version { $VERSION; }
27 @EXPORT = qw(&xsinit &ldopts
28 &ccopts &ccflags &ccdlflags &perl_inc
29 &xsi_header &xsi_protos &xsi_body);
31 #let's have Miniperl borrow from us instead
32 #require ExtUtils::Miniperl;
33 #*canon = \&ExtUtils::Miniperl::canon;
36 $lib_ext = $Config{lib_ext} || '.a';
39 my($file, $std, $mods) = @_;
41 $file ||= "perlxsi.c";
44 @mods = @$mods if $mods;
48 $file = $opt_o if defined $opt_o;
49 $std = $opt_s if defined $opt_s;
52 $std = 1 unless scalar @mods;
54 if ($file eq "STDOUT") {
58 $fh = new FileHandle "> $file";
61 push(@mods, static_ext()) if defined $std;
62 @mods = grep(!$seen{$_}++, @mods);
64 print $fh &xsi_header();
65 print $fh "EXTERN_C void xs_init _((void));\n\n";
66 print $fh &xsi_protos(@mods);
68 print $fh "\nEXTERN_C void\nxs_init()\n{\n";
69 print $fh &xsi_body(@mods);
86 # define EXTERN_C extern "C"
90 # define EXTERN_C extern
102 my($pname) = canon('/', $_);
104 ($mname = $pname) =~ s!/!::!g;
105 ($cname = $pname) =~ s!/!__!g;
106 my($ccode) = "EXTERN_C void boot_${cname} _((CV* cv));\n";
107 next if $seen{$ccode}++;
108 push(@retval, $ccode);
110 return join '', @retval;
115 my($pname,@retval,%seen);
116 my($dl) = canon('/','DynaLoader');
117 push(@retval, "\tchar *file = __FILE__;\n");
118 push(@retval, "\tdXSUB_SYS;\n") if $] > 5.002;
122 my($pname) = canon('/', $_);
123 my($mname, $cname, $ccode);
124 ($mname = $pname) =~ s!/!::!g;
125 ($cname = $pname) =~ s!/!__!g;
127 # Must NOT install 'DynaLoader::boot_DynaLoader' as 'bootstrap'!
128 # boot_DynaLoader is called directly in DynaLoader.pm
129 $ccode = "\t/* DynaLoader is a special case */\n\tnewXS(\"${mname}::boot_${cname}\", boot_${cname}, file);\n";
130 push(@retval, $ccode) unless $seen{$ccode}++;
132 $ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
133 push(@retval, $ccode) unless $seen{$ccode}++;
136 return join '', @retval;
140 unless (scalar @Extensions) {
141 @Extensions = sort split /\s+/, $Config{static_ext};
142 unshift @Extensions, qw(DynaLoader);
148 require ExtUtils::MakeMaker;
149 require ExtUtils::Liblist;
150 my($std,$mods,$link_args,$path) = @_;
151 my(@mods,@link_args,@argv);
152 my($dllib,$config_libs,@potential_libs,@path);
153 local($") = ' ' unless $" eq ' ';
154 my $MM = bless {} => 'MY';
156 @link_args = @$link_args if $link_args;
157 @mods = @$mods if $mods;
162 while($_ = shift @argv) {
163 /^-std$/ && do { $std = 1; next; };
164 /^--$/ && do { @link_args = @argv; last; };
165 /^-I(.*)/ && do { $path = $1 || shift @argv; next; };
169 $std = 1 unless scalar @link_args;
170 @path = $path ? split(/:/, $path) : @INC;
172 push(@potential_libs, @link_args) if scalar @link_args;
173 push(@potential_libs, $Config{libs}) if defined $std;
175 push(@mods, static_ext()) if $std;
177 my($mod,@ns,$root,$sub,$extra,$archive,@archives);
178 print STDERR "Searching (@path) for archives\n" if $Verbose;
179 foreach $mod (@mods) {
180 @ns = split('::', $mod);
182 $root = $MM->catdir(@ns);
184 print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
186 next unless -e ($archive = $MM->catdir($_,"auto",$root,"$sub$lib_ext"));
187 push @archives, $archive;
188 if(-e ($extra = $MM->catdir($_,"auto",$root,"extralibs.ld"))) {
190 if(open(FH, $extra)) {
191 my($libs) = <FH>; chomp $libs;
192 push @potential_libs, split /\s+/, $libs;
195 warn "Couldn't open '$extra'";
201 #print STDERR "\@potential_libs = @potential_libs\n";
203 my $libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";
205 my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
207 $MM->catdir("-L$Config{archlibexp}", "CORE"), " $libperl",
210 my $ld_or_bs = $bsloadlibs || $ldloadlibs;
211 print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
212 my $linkage = "$Config{ccdlflags} $Config{ldflags} @archives $ld_or_bs";
213 print STDERR "ldopts: '$linkage'\n" if $Verbose;
215 return $linkage if scalar @_;
220 print " $Config{ccflags} ";
224 print " $Config{ccdlflags} ";
228 print " -I$Config{archlibexp}/CORE ";
239 # might be X::Y or lib/auto/X/Y/Y.a
241 s:^(lib|ext)/(auto/)?::;
244 grep(s:/:$as:, @ext) if ($as ne '/');
252 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
257 perl -MExtUtils::Embed -e xsinit
258 perl -MExtUtils::Embed -e ldopts
262 ExtUtils::Embed provides utility functions for embedding a Perl interpreter
263 and extensions in your C/C++ applications.
264 Typically, an application B<Makefile> will invoke ExtUtils::Embed
265 functions while building your application.
269 ExtUtils::Embed exports the following functions:
271 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
272 ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
280 Generate C/C++ code for the XS initializer function.
282 When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
283 the following options are recognized:
285 B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
287 B<-o STDOUT> will print to STDOUT.
289 B<-std> (Write code for extensions that are linked with the current Perl.)
291 Any additional arguments are expected to be names of modules
292 to generate code for.
294 When invoked with parameters the following are accepted and optional:
296 C<xsinit($filename,$std,[@modules])>
300 B<$filename> is equivalent to the B<-o> option.
302 B<$std> is boolean, equivalent to the B<-std> option.
304 B<[@modules]> is an array ref, same as additional arguments mentioned above.
309 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
312 This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
313 to the C B<boot_Socket> function and writes it to a file named "xsinit.c".
315 Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
317 perl -MExtUtils::Embed -e xsinit
320 This will generate code for linking with B<DynaLoader> and
321 each static extension found in B<$Config{static_ext}>.
322 The code is written to the default file name B<perlxsi.c>.
325 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
328 Here, code is written for all the currently linked extensions along with code
329 for B<DBI> and B<DBD::Oracle>.
331 If you have a working B<DynaLoader> then there is rarely any need to statically link in any
336 Output arguments for linking the Perl library and extensions to your
339 When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
340 the following options are recognized:
344 Output arguments for linking the Perl library and any extensions linked
345 with the current Perl.
347 B<-I> E<lt>path1:path2E<gt>
349 Search path for ModuleName.a archives.
350 Default path is B<@INC>.
351 Library archives are expected to be found as
352 B</some/path/auto/ModuleName/ModuleName.a>
353 For example, when looking for B<Socket.a> relative to a search path,
354 we should find B<auto/Socket/Socket.a>
356 When looking for B<DBD::Oracle> relative to a search path,
357 we should find B<auto/DBD/Oracle/Oracle.a>
359 Keep in mind, you can always supply B</my/own/path/ModuleName.a>
360 as an additional linker argument.
362 B<--> E<lt>list of linker argsE<gt>
364 Additional linker arguments to be considered.
366 Any additional arguments found before the B<--> token
367 are expected to be names of modules to generate code for.
369 When invoked with parameters the following are accepted and optional:
371 C<ldopts($std,[@modules],[@link_args],$path)>
375 B<$std> is boolean, equivalent to the B<-std> option.
377 B<[@modules]> is equivalent to additional arguments found before the B<--> token.
379 B<[@link_args]> is equivalent to arguments found after the B<--> token.
381 B<$path> is equivalent to the B<-I> option.
383 In addition, when ldopts is called with parameters, it will return the argument string
384 rather than print it to STDOUT.
389 perl -MExtUtils::Embed -e ldopts
392 This will print arguments for linking with B<libperl.a>, B<DynaLoader> and
393 extensions found in B<$Config{static_ext}>. This includes libraries
394 found in B<$Config{libs}> and the first ModuleName.a library
395 for each extension that is found by searching B<@INC> or the path
396 specifed by the B<-I> option.
397 In addition, when ModuleName.a is found, additional linker arguments
398 are picked up from the B<extralibs.ld> file in the same directory.
401 perl -MExtUtils::Embed -e ldopts -- -std Socket
404 This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
407 perl -MExtUtils::Embed -e ldopts -- DynaLoader
410 This will print arguments for linking with just the B<DynaLoader> extension
414 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
417 Any arguments after the second '--' token are additional linker
418 arguments that will be examined for potential conflict. If there is no
419 conflict, the additional arguments will be part of the output.
424 For including perl header files this function simply prints:
426 -I$Config{archlibexp}/CORE
428 So, rather than having to say:
430 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
434 perl -MExtUtils::Embed -e perl_inc
436 =item ccflags(), ccdlflags()
438 These functions simply print $Config{ccflags} and $Config{ccdlflags}
442 This function combines perl_inc(), ccflags() and ccdlflags() into one.
446 This function simply returns a string defining the same B<EXTERN_C> macro as
447 B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
449 =item xsi_protos(@modules)
451 This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
453 =item xsi_body(@modules)
455 This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
456 function to B<boot_ModuleName> for each @modules.
458 B<xsinit()> uses the xsi_* functions to generate most of it's code.
464 For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
465 with embedded perl, see the eg/ directory and L<perlembed>.
473 Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
475 Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
476 B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.