1 # $Id: Embed.pm,v 1.1.1.1 2002/01/16 19:27:19 schwern Exp $
4 package ExtUtils::Embed;
11 #Only when we need them
12 #require ExtUtils::MakeMaker;
13 #require ExtUtils::Liblist;
15 use vars qw(@ISA @EXPORT $VERSION
16 @Extensions $Verbose $lib_ext
24 @EXPORT = qw(&xsinit &ldopts
25 &ccopts &ccflags &ccdlflags &perl_inc
26 &xsi_header &xsi_protos &xsi_body);
28 #let's have Miniperl borrow from us instead
29 #require ExtUtils::Miniperl;
30 #*canon = \&ExtUtils::Miniperl::canon;
33 $lib_ext = $Config{lib_ext} || '.a';
35 sub is_cmd { $0 eq '-e' }
48 my($file, $std, $mods) = @_;
50 $file ||= "perlxsi.c";
51 my $xsinit_proto = "pTHX";
54 @mods = @$mods if $mods;
58 $file = $opt_o if defined $opt_o;
59 $std = $opt_s if defined $opt_s;
62 $std = 1 unless scalar @mods;
64 if ($file eq "STDOUT") {
68 $fh = new FileHandle "> $file";
71 push(@mods, static_ext()) if defined $std;
72 @mods = grep(!$seen{$_}++, @mods);
74 print $fh &xsi_header();
75 print $fh "EXTERN_C void xs_init ($xsinit_proto);\n\n";
76 print $fh &xsi_protos(@mods);
78 print $fh "\nEXTERN_C void\nxs_init($xsinit_proto)\n{\n";
79 print $fh &xsi_body(@mods);
95 my $boot_proto = "pTHX_ CV* cv";
97 my($pname) = canon('/', $_);
99 ($mname = $pname) =~ s!/!::!g;
100 ($cname = $pname) =~ s!/!__!g;
101 my($ccode) = "EXTERN_C void boot_${cname} ($boot_proto);\n";
102 next if $seen{$ccode}++;
103 push(@retval, $ccode);
105 return join '', @retval;
110 my($pname,@retval,%seen);
111 my($dl) = canon('/','DynaLoader');
112 push(@retval, "\tchar *file = __FILE__;\n");
113 push(@retval, "\tdXSUB_SYS;\n") if $] > 5.002;
117 my($pname) = canon('/', $_);
118 my($mname, $cname, $ccode);
119 ($mname = $pname) =~ s!/!::!g;
120 ($cname = $pname) =~ s!/!__!g;
122 # Must NOT install 'DynaLoader::boot_DynaLoader' as 'bootstrap'!
123 # boot_DynaLoader is called directly in DynaLoader.pm
124 $ccode = "\t/* DynaLoader is a special case */\n\tnewXS(\"${mname}::boot_${cname}\", boot_${cname}, file);\n";
125 push(@retval, $ccode) unless $seen{$ccode}++;
127 $ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
128 push(@retval, $ccode) unless $seen{$ccode}++;
131 return join '', @retval;
135 unless (scalar @Extensions) {
136 @Extensions = sort split /\s+/, $Config{static_ext};
137 unshift @Extensions, qw(DynaLoader);
144 $$arg =~ s/([\(\)])/\\$1/g;
148 my $ldflags = $Config{ldflags};
154 my $ccflags = $Config{ccflags};
160 my $ccdlflags = $Config{ccdlflags};
161 _escape(\$ccdlflags);
166 require ExtUtils::MakeMaker;
167 require ExtUtils::Liblist;
168 my($std,$mods,$link_args,$path) = @_;
169 my(@mods,@link_args,@argv);
170 my($dllib,$config_libs,@potential_libs,@path);
171 local($") = ' ' unless $" eq ' ';
173 @link_args = @$link_args if $link_args;
174 @mods = @$mods if $mods;
179 while($_ = shift @argv) {
180 /^-std$/ && do { $std = 1; next; };
181 /^--$/ && do { @link_args = @argv; last; };
182 /^-I(.*)/ && do { $path = $1 || shift @argv; next; };
186 $std = 1 unless scalar @link_args;
187 my $sep = $Config{path_sep} || ':';
188 @path = $path ? split(/\Q$sep/, $path) : @INC;
190 push(@potential_libs, @link_args) if scalar @link_args;
191 # makemaker includes std libs on windows by default
192 if ($^O ne 'MSWin32' and defined($std)) {
193 push(@potential_libs, $Config{perllibs});
196 push(@mods, static_ext()) if $std;
198 my($mod,@ns,$root,$sub,$extra,$archive,@archives);
199 print STDERR "Searching (@path) for archives\n" if $Verbose;
200 foreach $mod (@mods) {
201 @ns = split(/::|\/|\\/, $mod);
203 $root = File::Spec->catdir(@ns);
205 print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
207 next unless -e ($archive = File::Spec->catdir($_,"auto",$root,"$sub$lib_ext"));
208 push @archives, $archive;
209 if(-e ($extra = File::Spec->catdir($_,"auto",$root,"extralibs.ld"))) {
211 if(open(FH, $extra)) {
212 my($libs) = <FH>; chomp $libs;
213 push @potential_libs, split /\s+/, $libs;
216 warn "Couldn't open '$extra'";
222 #print STDERR "\@potential_libs = @potential_libs\n";
225 if ($^O eq 'MSWin32') {
226 $libperl = $Config{libperl};
228 elsif ($^O eq 'os390' && $Config{usedl}) {
229 # Nothing for OS/390 (z/OS) dynamic.
231 $libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0]
232 || ($Config{libperl} =~ /^lib(\w+)(\Q$lib_ext\E|\.\Q$Config{dlext}\E)$/
237 my $lpath = File::Spec->catdir($Config{archlibexp}, 'CORE');
238 $lpath = qq["$lpath"] if $^O eq 'MSWin32';
239 my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
240 MM->ext(join ' ', "-L$lpath", $libperl, @potential_libs);
242 my $ld_or_bs = $bsloadlibs || $ldloadlibs;
243 print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
244 my $ccdlflags = _ccdlflags();
245 my $ldflags = _ldflags();
246 my $linkage = "$ccdlflags $ldflags @archives $ld_or_bs";
247 print STDERR "ldopts: '$linkage'\n" if $Verbose;
249 return $linkage if scalar @_;
250 my_return("$linkage\n");
254 my $ccflags = _ccflags();
255 my_return(" $ccflags ");
259 my $ccdlflags = _ccdlflags();
260 my_return(" $ccdlflags ");
264 my $dir = File::Spec->catdir($Config{archlibexp}, 'CORE');
265 $dir = qq["$dir"] if $^O eq 'MSWin32';
266 my_return(" -I$dir ");
276 # might be X::Y or lib/auto/X/Y/Y.a
278 s:^(lib|ext)/(auto/)?::;
281 grep(s:/:$as:, @ext) if ($as ne '/');
289 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
294 perl -MExtUtils::Embed -e xsinit
295 perl -MExtUtils::Embed -e ccopts
296 perl -MExtUtils::Embed -e ldopts
300 ExtUtils::Embed provides utility functions for embedding a Perl interpreter
301 and extensions in your C/C++ applications.
302 Typically, an application B<Makefile> will invoke ExtUtils::Embed
303 functions while building your application.
307 ExtUtils::Embed exports the following functions:
309 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
310 ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
318 Generate C/C++ code for the XS initializer function.
320 When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
321 the following options are recognized:
323 B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
325 B<-o STDOUT> will print to STDOUT.
327 B<-std> (Write code for extensions that are linked with the current Perl.)
329 Any additional arguments are expected to be names of modules
330 to generate code for.
332 When invoked with parameters the following are accepted and optional:
334 C<xsinit($filename,$std,[@modules])>
338 B<$filename> is equivalent to the B<-o> option.
340 B<$std> is boolean, equivalent to the B<-std> option.
342 B<[@modules]> is an array ref, same as additional arguments mentioned above.
347 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
350 This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
351 to the C B<boot_Socket> function and writes it to a file named F<xsinit.c>.
353 Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
355 perl -MExtUtils::Embed -e xsinit
358 This will generate code for linking with B<DynaLoader> and
359 each static extension found in B<$Config{static_ext}>.
360 The code is written to the default file name B<perlxsi.c>.
363 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
366 Here, code is written for all the currently linked extensions along with code
367 for B<DBI> and B<DBD::Oracle>.
369 If you have a working B<DynaLoader> then there is rarely any need to statically link in any
374 Output arguments for linking the Perl library and extensions to your
377 When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
378 the following options are recognized:
382 Output arguments for linking the Perl library and any extensions linked
383 with the current Perl.
385 B<-I> E<lt>path1:path2E<gt>
387 Search path for ModuleName.a archives.
388 Default path is B<@INC>.
389 Library archives are expected to be found as
390 B</some/path/auto/ModuleName/ModuleName.a>
391 For example, when looking for B<Socket.a> relative to a search path,
392 we should find B<auto/Socket/Socket.a>
394 When looking for B<DBD::Oracle> relative to a search path,
395 we should find B<auto/DBD/Oracle/Oracle.a>
397 Keep in mind that you can always supply B</my/own/path/ModuleName.a>
398 as an additional linker argument.
400 B<--> E<lt>list of linker argsE<gt>
402 Additional linker arguments to be considered.
404 Any additional arguments found before the B<--> token
405 are expected to be names of modules to generate code for.
407 When invoked with parameters the following are accepted and optional:
409 C<ldopts($std,[@modules],[@link_args],$path)>
413 B<$std> is boolean, equivalent to the B<-std> option.
415 B<[@modules]> is equivalent to additional arguments found before the B<--> token.
417 B<[@link_args]> is equivalent to arguments found after the B<--> token.
419 B<$path> is equivalent to the B<-I> option.
421 In addition, when ldopts is called with parameters, it will return the argument string
422 rather than print it to STDOUT.
427 perl -MExtUtils::Embed -e ldopts
430 This will print arguments for linking with B<libperl> and
431 extensions found in B<$Config{static_ext}>. This includes libraries
432 found in B<$Config{libs}> and the first ModuleName.a library
433 for each extension that is found by searching B<@INC> or the path
434 specified by the B<-I> option.
435 In addition, when ModuleName.a is found, additional linker arguments
436 are picked up from the B<extralibs.ld> file in the same directory.
439 perl -MExtUtils::Embed -e ldopts -- -std Socket
442 This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
444 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
446 Any arguments after the second '--' token are additional linker
447 arguments that will be examined for potential conflict. If there is no
448 conflict, the additional arguments will be part of the output.
453 For including perl header files this function simply prints:
455 -I$Config{archlibexp}/CORE
457 So, rather than having to say:
459 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
463 perl -MExtUtils::Embed -e perl_inc
465 =item ccflags(), ccdlflags()
467 These functions simply print $Config{ccflags} and $Config{ccdlflags}
471 This function combines perl_inc(), ccflags() and ccdlflags() into one.
475 This function simply returns a string defining the same B<EXTERN_C> macro as
476 B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
478 =item xsi_protos(@modules)
480 This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
482 =item xsi_body(@modules)
484 This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
485 function to B<boot_ModuleName> for each @modules.
487 B<xsinit()> uses the xsi_* functions to generate most of its code.
493 For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
494 with embedded perl, see L<perlembed>.
502 Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
504 Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
505 B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.