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.2505 $ =~ /(\d+)\.(\d+)/);
23 @EXPORT = qw(&xsinit &ldopts
24 &ccopts &ccflags &ccdlflags &perl_inc
25 &xsi_header &xsi_protos &xsi_body);
27 #let's have Miniperl borrow from us instead
28 #require ExtUtils::Miniperl;
29 #*canon = \&ExtUtils::Miniperl::canon;
32 $lib_ext = $Config{lib_ext} || '.a';
34 sub is_cmd { $0 eq '-e' }
47 $Config{ccflags} =~ /-DPERL_OBJECT/;
51 my($file, $std, $mods) = @_;
53 $file ||= "perlxsi.c";
54 my $xsinit_proto = is_perl_object() ? "CPERLarg" : "void";
57 @mods = @$mods if $mods;
61 $file = $opt_o if defined $opt_o;
62 $std = $opt_s if defined $opt_s;
65 $std = 1 unless scalar @mods;
67 if ($file eq "STDOUT") {
71 $fh = new FileHandle "> $file";
74 push(@mods, static_ext()) if defined $std;
75 @mods = grep(!$seen{$_}++, @mods);
77 print $fh &xsi_header();
78 print $fh "EXTERN_C void xs_init _(($xsinit_proto));\n\n";
79 print $fh &xsi_protos(@mods);
81 print $fh "\nEXTERN_C void\nxs_init($xsinit_proto)\n{\n";
82 print $fh &xsi_body(@mods);
89 #if defined(__cplusplus) && !defined(PERL_OBJECT)
102 #include "win32iop.h"
104 #include <perlhost.h>
109 # define EXTERN_C extern "C"
113 # define EXTERN_C extern
123 my $boot_proto = is_perl_object() ?
124 "CV* cv _CPERLarg" : "CV* cv";
126 my($pname) = canon('/', $_);
128 ($mname = $pname) =~ s!/!::!g;
129 ($cname = $pname) =~ s!/!__!g;
130 my($ccode) = "EXTERN_C void boot_${cname} _(($boot_proto));\n";
131 next if $seen{$ccode}++;
132 push(@retval, $ccode);
134 return join '', @retval;
139 my($pname,@retval,%seen);
140 my($dl) = canon('/','DynaLoader');
141 push(@retval, "\tchar *file = __FILE__;\n");
142 push(@retval, "\tdXSUB_SYS;\n") if $] > 5.002;
146 my($pname) = canon('/', $_);
147 my($mname, $cname, $ccode);
148 ($mname = $pname) =~ s!/!::!g;
149 ($cname = $pname) =~ s!/!__!g;
151 # Must NOT install 'DynaLoader::boot_DynaLoader' as 'bootstrap'!
152 # boot_DynaLoader is called directly in DynaLoader.pm
153 $ccode = "\t/* DynaLoader is a special case */\n\tnewXS(\"${mname}::boot_${cname}\", boot_${cname}, file);\n";
154 push(@retval, $ccode) unless $seen{$ccode}++;
156 $ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
157 push(@retval, $ccode) unless $seen{$ccode}++;
160 return join '', @retval;
164 unless (scalar @Extensions) {
165 @Extensions = sort split /\s+/, $Config{static_ext};
166 unshift @Extensions, qw(DynaLoader);
172 require ExtUtils::MakeMaker;
173 require ExtUtils::Liblist;
174 my($std,$mods,$link_args,$path) = @_;
175 my(@mods,@link_args,@argv);
176 my($dllib,$config_libs,@potential_libs,@path);
177 local($") = ' ' unless $" eq ' ';
178 my $MM = bless {} => 'MY';
180 @link_args = @$link_args if $link_args;
181 @mods = @$mods if $mods;
186 while($_ = shift @argv) {
187 /^-std$/ && do { $std = 1; next; };
188 /^--$/ && do { @link_args = @argv; last; };
189 /^-I(.*)/ && do { $path = $1 || shift @argv; next; };
193 $std = 1 unless scalar @link_args;
194 @path = $path ? split(/:/, $path) : @INC;
196 push(@potential_libs, @link_args) if scalar @link_args;
197 push(@potential_libs, $Config{libs}) if defined $std;
199 push(@mods, static_ext()) if $std;
201 my($mod,@ns,$root,$sub,$extra,$archive,@archives);
202 print STDERR "Searching (@path) for archives\n" if $Verbose;
203 foreach $mod (@mods) {
204 @ns = split(/::|\/|\\/, $mod);
206 $root = $MM->catdir(@ns);
208 print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
210 next unless -e ($archive = $MM->catdir($_,"auto",$root,"$sub$lib_ext"));
211 push @archives, $archive;
212 if(-e ($extra = $MM->catdir($_,"auto",$root,"extralibs.ld"))) {
214 if(open(FH, $extra)) {
215 my($libs) = <FH>; chomp $libs;
216 push @potential_libs, split /\s+/, $libs;
219 warn "Couldn't open '$extra'";
225 #print STDERR "\@potential_libs = @potential_libs\n";
227 my $libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";
229 my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
231 $MM->catdir("-L$Config{archlibexp}", "CORE"), " $libperl",
234 my $ld_or_bs = $bsloadlibs || $ldloadlibs;
235 print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
236 my $linkage = "$Config{ccdlflags} $Config{ldflags} @archives $ld_or_bs";
237 print STDERR "ldopts: '$linkage'\n" if $Verbose;
239 return $linkage if scalar @_;
240 my_return("$linkage\n");
244 my_return(" $Config{ccflags} ");
248 my_return(" $Config{ccdlflags} ");
252 my_return(" -I$Config{archlibexp}/CORE ");
262 # might be X::Y or lib/auto/X/Y/Y.a
264 s:^(lib|ext)/(auto/)?::;
267 grep(s:/:$as:, @ext) if ($as ne '/');
275 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
280 perl -MExtUtils::Embed -e xsinit
281 perl -MExtUtils::Embed -e ldopts
285 ExtUtils::Embed provides utility functions for embedding a Perl interpreter
286 and extensions in your C/C++ applications.
287 Typically, an application B<Makefile> will invoke ExtUtils::Embed
288 functions while building your application.
292 ExtUtils::Embed exports the following functions:
294 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
295 ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
303 Generate C/C++ code for the XS initializer function.
305 When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
306 the following options are recognized:
308 B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
310 B<-o STDOUT> will print to STDOUT.
312 B<-std> (Write code for extensions that are linked with the current Perl.)
314 Any additional arguments are expected to be names of modules
315 to generate code for.
317 When invoked with parameters the following are accepted and optional:
319 C<xsinit($filename,$std,[@modules])>
323 B<$filename> is equivalent to the B<-o> option.
325 B<$std> is boolean, equivalent to the B<-std> option.
327 B<[@modules]> is an array ref, same as additional arguments mentioned above.
332 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
335 This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
336 to the C B<boot_Socket> function and writes it to a file named "xsinit.c".
338 Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
340 perl -MExtUtils::Embed -e xsinit
343 This will generate code for linking with B<DynaLoader> and
344 each static extension found in B<$Config{static_ext}>.
345 The code is written to the default file name B<perlxsi.c>.
348 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
351 Here, code is written for all the currently linked extensions along with code
352 for B<DBI> and B<DBD::Oracle>.
354 If you have a working B<DynaLoader> then there is rarely any need to statically link in any
359 Output arguments for linking the Perl library and extensions to your
362 When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
363 the following options are recognized:
367 Output arguments for linking the Perl library and any extensions linked
368 with the current Perl.
370 B<-I> E<lt>path1:path2E<gt>
372 Search path for ModuleName.a archives.
373 Default path is B<@INC>.
374 Library archives are expected to be found as
375 B</some/path/auto/ModuleName/ModuleName.a>
376 For example, when looking for B<Socket.a> relative to a search path,
377 we should find B<auto/Socket/Socket.a>
379 When looking for B<DBD::Oracle> relative to a search path,
380 we should find B<auto/DBD/Oracle/Oracle.a>
382 Keep in mind, you can always supply B</my/own/path/ModuleName.a>
383 as an additional linker argument.
385 B<--> E<lt>list of linker argsE<gt>
387 Additional linker arguments to be considered.
389 Any additional arguments found before the B<--> token
390 are expected to be names of modules to generate code for.
392 When invoked with parameters the following are accepted and optional:
394 C<ldopts($std,[@modules],[@link_args],$path)>
398 B<$std> is boolean, equivalent to the B<-std> option.
400 B<[@modules]> is equivalent to additional arguments found before the B<--> token.
402 B<[@link_args]> is equivalent to arguments found after the B<--> token.
404 B<$path> is equivalent to the B<-I> option.
406 In addition, when ldopts is called with parameters, it will return the argument string
407 rather than print it to STDOUT.
412 perl -MExtUtils::Embed -e ldopts
415 This will print arguments for linking with B<libperl.a>, B<DynaLoader> and
416 extensions found in B<$Config{static_ext}>. This includes libraries
417 found in B<$Config{libs}> and the first ModuleName.a library
418 for each extension that is found by searching B<@INC> or the path
419 specifed by the B<-I> option.
420 In addition, when ModuleName.a is found, additional linker arguments
421 are picked up from the B<extralibs.ld> file in the same directory.
424 perl -MExtUtils::Embed -e ldopts -- -std Socket
427 This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
430 perl -MExtUtils::Embed -e ldopts -- DynaLoader
433 This will print arguments for linking with just the B<DynaLoader> extension
437 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
440 Any arguments after the second '--' token are additional linker
441 arguments that will be examined for potential conflict. If there is no
442 conflict, the additional arguments will be part of the output.
447 For including perl header files this function simply prints:
449 -I$Config{archlibexp}/CORE
451 So, rather than having to say:
453 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
457 perl -MExtUtils::Embed -e perl_inc
459 =item ccflags(), ccdlflags()
461 These functions simply print $Config{ccflags} and $Config{ccdlflags}
465 This function combines perl_inc(), ccflags() and ccdlflags() into one.
469 This function simply returns a string defining the same B<EXTERN_C> macro as
470 B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
472 =item xsi_protos(@modules)
474 This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
476 =item xsi_body(@modules)
478 This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
479 function to B<boot_ModuleName> for each @modules.
481 B<xsinit()> uses the xsi_* functions to generate most of it's code.
487 For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
488 with embedded perl, see the eg/ directory and L<perlembed>.
496 Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
498 Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
499 B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.