1 # $Id: Embed.pm,v 1.22 1997/01/30 00:37:09 dougm Exp $
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.2201 $ =~ /(\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, "\tdXSUB_SYS;\n") if $] > 5.002;
118 push(@retval, "\tchar *file = __FILE__;\n\n");
121 my($pname) = canon('/', $_);
122 my($mname, $cname, $ccode);
123 ($mname = $pname) =~ s!/!::!g;
124 ($cname = $pname) =~ s!/!__!g;
126 # Must NOT install 'DynaLoader::boot_DynaLoader' as 'bootstrap'!
127 # boot_DynaLoader is called directly in DynaLoader.pm
128 $ccode = "\t/* DynaLoader is a special case */\n\tnewXS(\"${mname}::boot_${cname}\", boot_${cname}, file);\n";
129 push(@retval, $ccode) unless $seen{$ccode}++;
131 $ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
132 push(@retval, $ccode) unless $seen{$ccode}++;
135 return join '', @retval;
139 unless (scalar @Extensions) {
140 @Extensions = sort split /\s+/, $Config{static_ext};
141 unshift @Extensions, qw(DynaLoader);
147 require ExtUtils::MakeMaker;
148 require ExtUtils::Liblist;
149 my($std,$mods,$link_args,$path) = @_;
150 my(@mods,@link_args,@argv);
151 my($dllib,$config_libs,@potential_libs,@path);
152 local($") = ' ' unless $" eq ' ';
153 my $MM = bless {} => 'MY';
155 @link_args = @$link_args if $link_args;
156 @mods = @$mods if $mods;
161 while($_ = shift @argv) {
162 /^-std$/ && do { $std = 1; next; };
163 /^--$/ && do { @link_args = @argv; last; };
164 /^-I(.*)/ && do { $path = $1 || shift @argv; next; };
168 $std = 1 unless scalar @link_args;
169 @path = $path ? split(/:/, $path) : @INC;
171 push(@potential_libs, @link_args) if scalar @link_args;
172 push(@potential_libs, $Config{libs}) if defined $std;
174 push(@mods, static_ext()) if $std;
176 my($mod,@ns,$root,$sub,$extra,$archive,@archives);
177 print STDERR "Searching (@path) for archives\n" if $Verbose;
178 foreach $mod (@mods) {
179 @ns = split('::', $mod);
181 $root = $MM->catdir(@ns);
183 print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
185 next unless -e ($archive = $MM->catdir($_,"auto",$root,"$sub$lib_ext"));
186 push @archives, $archive;
187 if(-e ($extra = $MM->catdir($_,"auto",$root,"extralibs.ld"))) {
189 if(open(FH, $extra)) {
190 my($libs) = <FH>; chomp $libs;
191 push @potential_libs, split /\s+/, $libs;
194 warn "Couldn't open '$extra'";
200 #print STDERR "\@potential_libs = @potential_libs\n";
202 my $libperl = (grep(/^(-l\w+perl)$/, @link_args))[0] || "-lperl";
204 my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
206 $MM->catdir("-L$Config{archlibexp}", "CORE"), " $libperl",
209 my $ld_or_bs = $bsloadlibs || $ldloadlibs;
210 print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
211 my $linkage = "$Config{ccdlflags} $Config{ldflags} @archives $ld_or_bs";
212 print STDERR "ldopts: '$linkage'\n" if $Verbose;
214 return $linkage if scalar @_;
219 print " $Config{ccflags} ";
223 print " $Config{ccdlflags} ";
227 print " -I$Config{archlibexp}/CORE ";
238 # might be X::Y or lib/auto/X/Y/Y.a
240 s:^(lib|ext)/(auto/)?::;
243 grep(s:/:$as:, @ext) if ($as ne '/');
251 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
256 perl -MExtUtils::Embed -e xsinit
257 perl -MExtUtils::Embed -e ldopts
261 ExtUtils::Embed provides utility functions for embedding a Perl interpreter
262 and extensions in your C/C++ applications.
263 Typically, an application B<Makefile> will invoke ExtUtils::Embed
264 functions while building your application.
268 ExtUtils::Embed exports the following functions:
270 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
271 ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
279 Generate C/C++ code for the XS initializer function.
281 When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
282 the following options are recognized:
284 B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
286 B<-o STDOUT> will print to STDOUT.
288 B<-std> (Write code for extensions that are linked with the current Perl.)
290 Any additional arguments are expected to be names of modules
291 to generate code for.
293 When invoked with parameters the following are accepted and optional:
295 C<xsinit($filename,$std,[@modules])>
299 B<$filename> is equivalent to the B<-o> option.
301 B<$std> is boolean, equivalent to the B<-std> option.
303 B<[@modules]> is an array ref, same as additional arguments mentioned above.
308 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
311 This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
312 to the C B<boot_Socket> function and writes it to a file named "xsinit.c".
314 Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
316 perl -MExtUtils::Embed -e xsinit
319 This will generate code for linking with B<DynaLoader> and
320 each static extension found in B<$Config{static_ext}>.
321 The code is written to the default file name B<perlxsi.c>.
324 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
327 Here, code is written for all the currently linked extensions along with code
328 for B<DBI> and B<DBD::Oracle>.
330 If you have a working B<DynaLoader> then there is rarely any need to statically link in any
335 Output arguments for linking the Perl library and extensions to your
338 When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
339 the following options are recognized:
343 Output arguments for linking the Perl library and any extensions linked
344 with the current Perl.
346 B<-I> E<lt>path1:path2E<gt>
348 Search path for ModuleName.a archives.
349 Default path is B<@INC>.
350 Library archives are expected to be found as
351 B</some/path/auto/ModuleName/ModuleName.a>
352 For example, when looking for B<Socket.a> relative to a search path,
353 we should find B<auto/Socket/Socket.a>
355 When looking for B<DBD::Oracle> relative to a search path,
356 we should find B<auto/DBD/Oracle/Oracle.a>
358 Keep in mind, you can always supply B</my/own/path/ModuleName.a>
359 as an additional linker argument.
361 B<--> E<lt>list of linker argsE<gt>
363 Additional linker arguments to be considered.
365 Any additional arguments found before the B<--> token
366 are expected to be names of modules to generate code for.
368 When invoked with parameters the following are accepted and optional:
370 C<ldopts($std,[@modules],[@link_args],$path)>
374 B<$std> is boolean, equivalent to the B<-std> option.
376 B<[@modules]> is equivalent to additional arguments found before the B<--> token.
378 B<[@link_args]> is equivalent to arguments found after the B<--> token.
380 B<$path> is equivalent to the B<-I> option.
382 In addition, when ldopts is called with parameters, it will return the argument string
383 rather than print it to STDOUT.
388 perl -MExtUtils::Embed -e ldopts
391 This will print arguments for linking with B<libperl.a>, B<DynaLoader> and
392 extensions found in B<$Config{static_ext}>. This includes libraries
393 found in B<$Config{libs}> and the first ModuleName.a library
394 for each extension that is found by searching B<@INC> or the path
395 specifed by the B<-I> option.
396 In addition, when ModuleName.a is found, additional linker arguments
397 are picked up from the B<extralibs.ld> file in the same directory.
400 perl -MExtUtils::Embed -e ldopts -- -std Socket
403 This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
406 perl -MExtUtils::Embed -e ldopts -- DynaLoader
409 This will print arguments for linking with just the B<DynaLoader> extension
413 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
416 Any arguments after the second '--' token are additional linker
417 arguments that will be examined for potential conflict. If there is no
418 conflict, the additional arguments will be part of the output.
423 For including perl header files this function simply prints:
425 -I$Config{archlibexp}/CORE
427 So, rather than having to say:
429 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
433 perl -MExtUtils::Embed -e perl_inc
435 =item ccflags(), ccdlflags()
437 These functions simply print $Config{ccflags} and $Config{ccdlflags}
441 This function combines perl_inc(), ccflags() and ccdlflags() into one.
445 This function simply returns a string defining the same B<EXTERN_C> macro as
446 B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
448 =item xsi_protos(@modules)
450 This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
452 =item xsi_body(@modules)
454 This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
455 function to B<boot_ModuleName> for each @modules.
457 B<xsinit()> uses the xsi_* functions to generate most of it's code.
463 For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
464 with embedded perl, see the eg/ directory and L<perlembed>.
472 Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
474 Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
475 B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.