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.22 $ =~ /(\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($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
204 $MM->catdir("-L$Config{archlibexp}", "CORE"), " -lperl",
207 my $ld_or_bs = $bsloadlibs || $ldloadlibs;
208 print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
209 my $linkage = "$Config{ccdlflags} $Config{ldflags} @archives $ld_or_bs";
210 print STDERR "ldopts: '$linkage'\n" if $Verbose;
212 return $linkage if scalar @_;
217 print " $Config{ccflags} ";
221 print " $Config{ccdlflags} ";
225 print " -I$Config{archlibexp}/CORE ";
236 # might be X::Y or lib/auto/X/Y/Y.a
238 s:^(lib|ext)/(auto/)?::;
241 grep(s:/:$as:, @ext) if ($as ne '/');
249 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
254 perl -MExtUtils::Embed -e xsinit
255 perl -MExtUtils::Embed -e ldopts
259 ExtUtils::Embed provides utility functions for embedding a Perl interpreter
260 and extensions in your C/C++ applications.
261 Typically, an application B<Makefile> will invoke ExtUtils::Embed
262 functions while building your application.
266 ExtUtils::Embed exports the following functions:
268 xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
269 ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
275 Generate C/C++ code for the XS initializer function.
277 When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
278 the following options are recognized:
280 B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
282 B<-o STDOUT> will print to STDOUT.
284 B<-std> (Write code for extensions that are linked with the current Perl.)
286 Any additional arguments are expected to be names of modules
287 to generate code for.
289 When invoked with parameters the following are accepted and optional:
291 C<xsinit($filename,$std,[@modules])>
295 B<$filename> is equivalent to the B<-o> option.
297 B<$std> is boolean, equivalent to the B<-std> option.
299 B<[@modules]> is an array ref, same as additional arguments mentioned above.
304 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
307 This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
308 to the C B<boot_Socket> function and writes it to a file named "xsinit.c".
310 Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
312 perl -MExtUtils::Embed -e xsinit
315 This will generate code for linking with B<DynaLoader> and
316 each static extension found in B<$Config{static_ext}>.
317 The code is written to the default file name B<perlxsi.c>.
320 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
323 Here, code is written for all the currently linked extensions along with code
324 for B<DBI> and B<DBD::Oracle>.
326 If you have a working B<DynaLoader> then there is rarely any need to statically link in any
331 Output arguments for linking the Perl library and extensions to your
334 When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
335 the following options are recognized:
339 Output arguments for linking the Perl library and any extensions linked
340 with the current Perl.
342 B<-I> E<lt>path1:path2E<gt>
344 Search path for ModuleName.a archives.
345 Default path is B<@INC>.
346 Library archives are expected to be found as
347 B</some/path/auto/ModuleName/ModuleName.a>
348 For example, when looking for B<Socket.a> relative to a search path,
349 we should find B<auto/Socket/Socket.a>
351 When looking for B<DBD::Oracle> relative to a search path,
352 we should find B<auto/DBD/Oracle/Oracle.a>
354 Keep in mind, you can always supply B</my/own/path/ModuleName.a>
355 as an additional linker argument.
357 B<--> E<lt>list of linker argsE<gt>
359 Additional linker arguments to be considered.
361 Any additional arguments found before the B<--> token
362 are expected to be names of modules to generate code for.
364 When invoked with parameters the following are accepted and optional:
366 C<ldopts($std,[@modules],[@link_args],$path)>
370 B<$std> is boolean, equivalent to the B<-std> option.
372 B<[@modules]> is equivalent to additional arguments found before the B<--> token.
374 B<[@link_args]> is equivalent to arguments found after the B<--> token.
376 B<$path> is equivalent to the B<-I> option.
378 In addition, when ldopts is called with parameters, it will return the argument string
379 rather than print it to STDOUT.
384 perl -MExtUtils::Embed -e ldopts
387 This will print arguments for linking with B<libperl.a>, B<DynaLoader> and
388 extensions found in B<$Config{static_ext}>. This includes libraries
389 found in B<$Config{libs}> and the first ModuleName.a library
390 for each extension that is found by searching B<@INC> or the path
391 specifed by the B<-I> option.
392 In addition, when ModuleName.a is found, additional linker arguments
393 are picked up from the B<extralibs.ld> file in the same directory.
396 perl -MExtUtils::Embed -e ldopts -- -std Socket
399 This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
402 perl -MExtUtils::Embed -e ldopts -- DynaLoader
405 This will print arguments for linking with just the B<DynaLoader> extension
409 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
412 Any arguments after the second '--' token are additional linker
413 arguments that will be examined for potential conflict. If there is no
414 conflict, the additional arguments will be part of the output.
419 For including perl header files this function simply prints:
421 -I$Config{archlibexp}/CORE
423 So, rather than having to say:
425 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
429 perl -MExtUtils::Embed -e perl_inc
431 =item ccflags(), ccdlflags()
433 These functions simply print $Config{ccflags} and $Config{ccdlflags}
437 This function combines perl_inc(), ccflags() and ccdlflags() into one.
441 This function simply returns a string defining the same B<EXTERN_C> macro as
442 B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
444 =item xsi_protos(@modules)
446 This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
448 =item xsi_body(@modules)
450 This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
451 function to B<boot_ModuleName> for each @modules.
453 B<xsinit()> uses the xsi_* functions to generate most of it's code.
457 For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
458 with embedded perl, see the eg/ directory and L<perlembed>.
466 Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
468 Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
469 B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.