lib/ExtUtils/Embed.pm

# $Id: Embed.pm,v 1.1.1.1 2002/01/16 19:27:19 schwern Exp $
require 5.002;

package ExtUtils::Embed;
require Exporter;
require FileHandle;
use Config;
use Getopt::Std;
use File::Spec;

#Only when we need them
#require ExtUtils::MakeMaker;
#require ExtUtils::Liblist;

use vars qw(@ISA @EXPORT $VERSION
            @Extensions $Verbose $lib_ext
            $opt_o $opt_s 
            );
use strict;

$VERSION = 1.2506_01;

@ISA = qw(Exporter);
@EXPORT = qw(&xsinit &ldopts 
             &ccopts &ccflags &ccdlflags &perl_inc
             &xsi_header &xsi_protos &xsi_body);

#let's have Miniperl borrow from us instead
#require ExtUtils::Miniperl;
#*canon = \&ExtUtils::Miniperl::canon;

$Verbose = 0;
$lib_ext = $Config{lib_ext} || '.a';

sub is_cmd { $0 eq '-e' }

sub my_return {
    my $val = shift;
    if(is_cmd) {
        print $val;
    }
    else {
        return $val;
    }
}

sub xsinit { 
    my($file, $std, $mods) = @_;
    my($fh,@mods,%seen);
    $file ||= "perlxsi.c";
    my $xsinit_proto = "pTHX";

    if (@_) {
       @mods = @$mods if $mods;
    }
    else {
       getopts('o:s:');
       $file = $opt_o if defined $opt_o;
       $std  = $opt_s  if defined $opt_s;
       @mods = @ARGV;
    }
    $std = 1 unless scalar @mods;

    if ($file eq "STDOUT") {
        $fh = \*STDOUT;
    }
    else {
        $fh = new FileHandle "> $file";
    }

    push(@mods, static_ext()) if defined $std;
    @mods = grep(!$seen{$_}++, @mods);

    print $fh &xsi_header();
    print $fh "EXTERN_C void xs_init ($xsinit_proto);\n\n";     
    print $fh &xsi_protos(@mods);

    print $fh "\nEXTERN_C void\nxs_init($xsinit_proto)\n{\n";
    print $fh &xsi_body(@mods);
    print $fh "}\n";

}

sub xsi_header {
    return <<EOF;
#include <EXTERN.h>
#include <perl.h>

EOF
}    

sub xsi_protos {
    my(@exts) = @_;
    my(@retval,%seen);
    my $boot_proto = "pTHX_ CV* cv";
    foreach $_ (@exts){
        my($pname) = canon('/', $_);
        my($mname, $cname);
        ($mname = $pname) =~ s!/!::!g;
        ($cname = $pname) =~ s!/!__!g;
        my($ccode) = "EXTERN_C void boot_${cname} ($boot_proto);\n";
        next if $seen{$ccode}++;
        push(@retval, $ccode);
    }
    return join '', @retval;
}

sub xsi_body {
    my(@exts) = @_;
    my($pname,@retval,%seen);
    my($dl) = canon('/','DynaLoader');
    push(@retval, "\tchar *file = __FILE__;\n");
    push(@retval, "\tdXSUB_SYS;\n") if $] > 5.002;
    push(@retval, "\n");

    foreach $_ (@exts){
        my($pname) = canon('/', $_);
        my($mname, $cname, $ccode);
        ($mname = $pname) =~ s!/!::!g;
        ($cname = $pname) =~ s!/!__!g;
        if ($pname eq $dl){
            # Must NOT install 'DynaLoader::boot_DynaLoader' as 'bootstrap'!
            # boot_DynaLoader is called directly in DynaLoader.pm
            $ccode = "\t/* DynaLoader is a special case */\n\tnewXS(\"${mname}::boot_${cname}\", boot_${cname}, file);\n";
            push(@retval, $ccode) unless $seen{$ccode}++;
        } else {
            $ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
            push(@retval, $ccode) unless $seen{$ccode}++;
        }
    }
    return join '', @retval;
}

sub static_ext {
    unless (scalar @Extensions) {
        @Extensions = sort split /\s+/, $Config{static_ext};
        unshift @Extensions, qw(DynaLoader);
    }
    @Extensions;
}

sub _escape {
    my $arg = shift;
    $$arg =~ s/([\(\)])/\\$1/g;
}

sub _ldflags {
    my $ldflags = $Config{ldflags};
    _escape(\$ldflags);
    return $ldflags;
}

sub _ccflags {
    my $ccflags = $Config{ccflags};
    _escape(\$ccflags);
    return $ccflags;
}

sub _ccdlflags {
    my $ccdlflags = $Config{ccdlflags};
    _escape(\$ccdlflags);
    return $ccdlflags;
}

sub ldopts {
    require ExtUtils::MakeMaker;
    require ExtUtils::Liblist;
    my($std,$mods,$link_args,$path) = @_;
    my(@mods,@link_args,@argv);
    my($dllib,$config_libs,@potential_libs,@path);
    local($") = ' ' unless $" eq ' ';
    if (scalar @_) {
       @link_args = @$link_args if $link_args;
       @mods = @$mods if $mods;
    }
    else {
       @argv = @ARGV;
       #hmm
       while($_ = shift @argv) {
           /^-std$/  && do { $std = 1; next; };
           /^--$/    && do { @link_args = @argv; last; };
           /^-I(.*)/ && do { $path = $1 || shift @argv; next; };
           push(@mods, $_); 
       }
    }
    $std = 1 unless scalar @link_args;
    my $sep = $Config{path_sep} || ':';
    @path = $path ? split(/\Q$sep/, $path) : @INC;

    push(@potential_libs, @link_args)    if scalar @link_args;
    # makemaker includes std libs on windows by default
    if ($^O ne 'MSWin32' and defined($std)) {
        push(@potential_libs, $Config{perllibs});
    }

    push(@mods, static_ext()) if $std;

    my($mod,@ns,$root,$sub,$extra,$archive,@archives);
    print STDERR "Searching (@path) for archives\n" if $Verbose;
    foreach $mod (@mods) {
        @ns = split(/::|\/|\\/, $mod);
        $sub = $ns[-1];
        $root = File::Spec->catdir(@ns);
        
        print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
        foreach (@path) {
            next unless -e ($archive = File::Spec->catdir($_,"auto",$root,"$sub$lib_ext"));
            push @archives, $archive;
            if(-e ($extra = File::Spec->catdir($_,"auto",$root,"extralibs.ld"))) {
                local(*FH); 
                if(open(FH, $extra)) {
                    my($libs) = <FH>; chomp $libs;
                    push @potential_libs, split /\s+/, $libs;
                }
                else {  
                    warn "Couldn't open '$extra'"; 
                }
            }
            last;
        }
    }
    #print STDERR "\@potential_libs = @potential_libs\n";

    my $libperl;
    if ($^O eq 'MSWin32') {
        $libperl = $Config{libperl};
    }
    else {
        $libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";
    }

    my $lpath = File::Spec->catdir($Config{archlibexp}, 'CORE');
    $lpath = qq["$lpath"] if $^O eq 'MSWin32';
    my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
        MM->ext(join ' ', "-L$lpath", $libperl, @potential_libs);

    my $ld_or_bs = $bsloadlibs || $ldloadlibs;
    print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
    my $ccdlflags = _ccdlflags();
    my $ldflags   = _ldflags();
    my $linkage = "$ccdlflags $ldflags @archives $ld_or_bs";
    print STDERR "ldopts: '$linkage'\n" if $Verbose;

    return $linkage if scalar @_;
    my_return("$linkage\n");
}

sub ccflags {
    my $ccflags = _ccflags();
    my_return(" $ccflags ");
}

sub ccdlflags {
    my $ccdlflags = _ccdlflags();
    my_return(" $ccdlflags ");
}

sub perl_inc {
    my $dir = File::Spec->catdir($Config{archlibexp}, 'CORE');
    $dir = qq["$dir"] if $^O eq 'MSWin32';
    my_return(" -I$dir ");
}

sub ccopts {
   ccflags . perl_inc;
}

sub canon {
    my($as, @ext) = @_;
    foreach(@ext) {
       # might be X::Y or lib/auto/X/Y/Y.a
       next if s!::!/!g;
       s:^(lib|ext)/(auto/)?::;
       s:/\w+\.\w+$::;
    }
    grep(s:/:$as:, @ext) if ($as ne '/');
    @ext;
}

__END__

=head1 NAME

ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications

=head1 SYNOPSIS


 perl -MExtUtils::Embed -e xsinit 
 perl -MExtUtils::Embed -e ccopts 
 perl -MExtUtils::Embed -e ldopts 

=head1 DESCRIPTION

ExtUtils::Embed provides utility functions for embedding a Perl interpreter
and extensions in your C/C++ applications.  
Typically, an application B<Makefile> will invoke ExtUtils::Embed
functions while building your application.  

=head1 @EXPORT

ExtUtils::Embed exports the following functions:

xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(), 
ccdlflags(), xsi_header(), xsi_protos(), xsi_body()

=head1 FUNCTIONS

=over 4

=item xsinit()

Generate C/C++ code for the XS initializer function.

When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
the following options are recognized:

B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)

B<-o STDOUT> will print to STDOUT.

B<-std> (Write code for extensions that are linked with the current Perl.)

Any additional arguments are expected to be names of modules
to generate code for.

When invoked with parameters the following are accepted and optional:

C<xsinit($filename,$std,[@modules])>

Where,

B<$filename> is equivalent to the B<-o> option.

B<$std> is boolean, equivalent to the B<-std> option.  

B<[@modules]> is an array ref, same as additional arguments mentioned above.

=item Examples


 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket


This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function 
to the C B<boot_Socket> function and writes it to a file named F<xsinit.c>.

Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.

 perl -MExtUtils::Embed -e xsinit


This will generate code for linking with B<DynaLoader> and 
each static extension found in B<$Config{static_ext}>.
The code is written to the default file name B<perlxsi.c>.


 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle


Here, code is written for all the currently linked extensions along with code
for B<DBI> and B<DBD::Oracle>.

If you have a working B<DynaLoader> then there is rarely any need to statically link in any 
other extensions.

=item ldopts()

Output arguments for linking the Perl library and extensions to your
application.

When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
the following options are recognized:

B<-std> 

Output arguments for linking the Perl library and any extensions linked
with the current Perl.

B<-I> E<lt>path1:path2E<gt>

Search path for ModuleName.a archives.  
Default path is B<@INC>.
Library archives are expected to be found as 
B</some/path/auto/ModuleName/ModuleName.a>
For example, when looking for B<Socket.a> relative to a search path, 
we should find B<auto/Socket/Socket.a>  

When looking for B<DBD::Oracle> relative to a search path,
we should find B<auto/DBD/Oracle/Oracle.a>

Keep in mind that you can always supply B</my/own/path/ModuleName.a>
as an additional linker argument.

B<-->  E<lt>list of linker argsE<gt>

Additional linker arguments to be considered.

Any additional arguments found before the B<--> token 
are expected to be names of modules to generate code for.

When invoked with parameters the following are accepted and optional:

C<ldopts($std,[@modules],[@link_args],$path)>

Where:

B<$std> is boolean, equivalent to the B<-std> option.  

B<[@modules]> is equivalent to additional arguments found before the B<--> token.

B<[@link_args]> is equivalent to arguments found after the B<--> token.

B<$path> is equivalent to the B<-I> option.

In addition, when ldopts is called with parameters, it will return the argument string
rather than print it to STDOUT.

=item Examples


 perl -MExtUtils::Embed -e ldopts


This will print arguments for linking with B<libperl.a>, B<DynaLoader> and 
extensions found in B<$Config{static_ext}>.  This includes libraries
found in B<$Config{libs}> and the first ModuleName.a library
for each extension that is found by searching B<@INC> or the path 
specified by the B<-I> option.  
In addition, when ModuleName.a is found, additional linker arguments
are picked up from the B<extralibs.ld> file in the same directory.


 perl -MExtUtils::Embed -e ldopts -- -std Socket


This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.


 perl -MExtUtils::Embed -e ldopts -- DynaLoader


This will print arguments for linking with just the B<DynaLoader> extension
and B<libperl.a>.


 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql


Any arguments after the second '--' token are additional linker
arguments that will be examined for potential conflict.  If there is no
conflict, the additional arguments will be part of the output.  


=item perl_inc()

For including perl header files this function simply prints:

 -I$Config{archlibexp}/CORE  

So, rather than having to say:

 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'

Just say:

 perl -MExtUtils::Embed -e perl_inc

=item ccflags(), ccdlflags()

These functions simply print $Config{ccflags} and $Config{ccdlflags}

=item ccopts()

This function combines perl_inc(), ccflags() and ccdlflags() into one.

=item xsi_header()

This function simply returns a string defining the same B<EXTERN_C> macro as
B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.  

=item xsi_protos(@modules)

This function returns a string of B<boot_$ModuleName> prototypes for each @modules.

=item xsi_body(@modules)

This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
function to B<boot_ModuleName> for each @modules.

B<xsinit()> uses the xsi_* functions to generate most of its code.

=back

=head1 EXAMPLES

For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
with embedded perl, see L<perlembed>.

=head1 SEE ALSO

L<perlembed>

=head1 AUTHOR

Doug MacEachern E<lt>F<dougm@osf.org>E<gt>

Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.

=cut

Revision:	1.1.2.1
Committed:	Thu Jun 30 14:59:14 2005 UTC (21 years, 4 months ago) by root
Branch:	PERL
CVS Tags:	PERL-5-8-7
Changes since 1.1:	+0 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	# $Id: Embed.pm,v 1.1.1.1 2002/01/16 19:27:19 schwern Exp $
2			require 5.002;
3
4			package ExtUtils::Embed;
5			require Exporter;
6			require FileHandle;
7			use Config;
8			use Getopt::Std;
9			use File::Spec;
10
11			#Only when we need them
12			#require ExtUtils::MakeMaker;
13			#require ExtUtils::Liblist;
14
15			use vars qw(@ISA @EXPORT $VERSION
16			@Extensions $Verbose $lib_ext
17			$opt_o $opt_s
18			);
19			use strict;
20
21			$VERSION = 1.2506_01;
22
23			@ISA = qw(Exporter);
24			@EXPORT = qw(&xsinit &ldopts
25			&ccopts &ccflags &ccdlflags &perl_inc
26			&xsi_header &xsi_protos &xsi_body);
27
28			#let's have Miniperl borrow from us instead
29			#require ExtUtils::Miniperl;
30			#*canon = \&ExtUtils::Miniperl::canon;
31
32			$Verbose = 0;
33			$lib_ext = $Config{lib_ext} \|\| '.a';
34
35			sub is_cmd { $0 eq '-e' }
36
37			sub my_return {
38			my $val = shift;
39			if(is_cmd) {
40			print $val;
41			}
42			else {
43			return $val;
44			}
45			}
46
47			sub xsinit {
48			my($file, $std, $mods) = @_;
49			my($fh,@mods,%seen);
50			$file \|\|= "perlxsi.c";
51			my $xsinit_proto = "pTHX";
52
53			if (@_) {
54			@mods = @$mods if $mods;
55			}
56			else {
57			getopts('o:s:');
58			$file = $opt_o if defined $opt_o;
59			$std = $opt_s if defined $opt_s;
60			@mods = @ARGV;
61			}
62			$std = 1 unless scalar @mods;
63
64			if ($file eq "STDOUT") {
65			$fh = \*STDOUT;
66			}
67			else {
68			$fh = new FileHandle "> $file";
69			}
70
71			push(@mods, static_ext()) if defined $std;
72			@mods = grep(!$seen{$_}++, @mods);
73
74			print $fh &xsi_header();
75			print $fh "EXTERN_C void xs_init ($xsinit_proto);\n\n";
76			print $fh &xsi_protos(@mods);
77
78			print $fh "\nEXTERN_C void\nxs_init($xsinit_proto)\n{\n";
79			print $fh &xsi_body(@mods);
80			print $fh "}\n";
81
82			}
83
84			sub xsi_header {
85			return <<EOF;
86			#include <EXTERN.h>
87			#include <perl.h>
88
89			EOF
90			}
91
92			sub xsi_protos {
93			my(@exts) = @_;
94			my(@retval,%seen);
95			my $boot_proto = "pTHX_ CV* cv";
96			foreach $_ (@exts){
97			my($pname) = canon('/', $_);
98			my($mname, $cname);
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);
104			}
105			return join '', @retval;
106			}
107
108			sub xsi_body {
109			my(@exts) = @_;
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;
114			push(@retval, "\n");
115
116			foreach $_ (@exts){
117			my($pname) = canon('/', $_);
118			my($mname, $cname, $ccode);
119			($mname = $pname) =~ s!/!::!g;
120			($cname = $pname) =~ s!/!__!g;
121			if ($pname eq $dl){
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}++;
126			} else {
127			$ccode = "\tnewXS(\"${mname}::bootstrap\", boot_${cname}, file);\n";
128			push(@retval, $ccode) unless $seen{$ccode}++;
129			}
130			}
131			return join '', @retval;
132			}
133
134			sub static_ext {
135			unless (scalar @Extensions) {
136			@Extensions = sort split /\s+/, $Config{static_ext};
137			unshift @Extensions, qw(DynaLoader);
138			}
139			@Extensions;
140			}
141
142			sub _escape {
143			my $arg = shift;
144			$$arg =~ s/([\(\)])/\\$1/g;
145			}
146
147			sub _ldflags {
148			my $ldflags = $Config{ldflags};
149			_escape(\$ldflags);
150			return $ldflags;
151			}
152
153			sub _ccflags {
154			my $ccflags = $Config{ccflags};
155			_escape(\$ccflags);
156			return $ccflags;
157			}
158
159			sub _ccdlflags {
160			my $ccdlflags = $Config{ccdlflags};
161			_escape(\$ccdlflags);
162			return $ccdlflags;
163			}
164
165			sub ldopts {
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 ' ';
172			if (scalar @_) {
173			@link_args = @$link_args if $link_args;
174			@mods = @$mods if $mods;
175			}
176			else {
177			@argv = @ARGV;
178			#hmm
179			while($_ = shift @argv) {
180			/^-std$/ && do { $std = 1; next; };
181			/^--$/ && do { @link_args = @argv; last; };
182			/^-I(.*)/ && do { $path = $1 \|\| shift @argv; next; };
183			push(@mods, $_);
184			}
185			}
186			$std = 1 unless scalar @link_args;
187			my $sep = $Config{path_sep} \|\| ':';
188			@path = $path ? split(/\Q$sep/, $path) : @INC;
189
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});
194			}
195
196			push(@mods, static_ext()) if $std;
197
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);
202			$sub = $ns[-1];
203			$root = File::Spec->catdir(@ns);
204
205			print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
206			foreach (@path) {
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"))) {
210			local(*FH);
211			if(open(FH, $extra)) {
212			my($libs) = <FH>; chomp $libs;
213			push @potential_libs, split /\s+/, $libs;
214			}
215			else {
216			warn "Couldn't open '$extra'";
217			}
218			}
219			last;
220			}
221			}
222			#print STDERR "\@potential_libs = @potential_libs\n";
223
224			my $libperl;
225			if ($^O eq 'MSWin32') {
226			$libperl = $Config{libperl};
227			}
228			else {
229			$libperl = (grep(/^-l\wperl\w$/, @link_args))[0] \|\| "-lperl";
230			}
231
232			my $lpath = File::Spec->catdir($Config{archlibexp}, 'CORE');
233			$lpath = qq["$lpath"] if $^O eq 'MSWin32';
234			my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
235			MM->ext(join ' ', "-L$lpath", $libperl, @potential_libs);
236
237			my $ld_or_bs = $bsloadlibs \|\| $ldloadlibs;
238			print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
239			my $ccdlflags = _ccdlflags();
240			my $ldflags = _ldflags();
241			my $linkage = "$ccdlflags $ldflags @archives $ld_or_bs";
242			print STDERR "ldopts: '$linkage'\n" if $Verbose;
243
244			return $linkage if scalar @_;
245			my_return("$linkage\n");
246			}
247
248			sub ccflags {
249			my $ccflags = _ccflags();
250			my_return(" $ccflags ");
251			}
252
253			sub ccdlflags {
254			my $ccdlflags = _ccdlflags();
255			my_return(" $ccdlflags ");
256			}
257
258			sub perl_inc {
259			my $dir = File::Spec->catdir($Config{archlibexp}, 'CORE');
260			$dir = qq["$dir"] if $^O eq 'MSWin32';
261			my_return(" -I$dir ");
262			}
263
264			sub ccopts {
265			ccflags . perl_inc;
266			}
267
268			sub canon {
269			my($as, @ext) = @_;
270			foreach(@ext) {
271			# might be X::Y or lib/auto/X/Y/Y.a
272			next if s!::!/!g;
273			s:^(lib\|ext)/(auto/)?::;
274			s:/\w+\.\w+$::;
275			}
276			grep(s:/:$as:, @ext) if ($as ne '/');
277			@ext;
278			}
279
280			__END__
281
282			=head1 NAME
283
284			ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
285
286			=head1 SYNOPSIS
287
288
289			perl -MExtUtils::Embed -e xsinit
290			perl -MExtUtils::Embed -e ccopts
291			perl -MExtUtils::Embed -e ldopts
292
293			=head1 DESCRIPTION
294
295			ExtUtils::Embed provides utility functions for embedding a Perl interpreter
296			and extensions in your C/C++ applications.
297			Typically, an application B<Makefile> will invoke ExtUtils::Embed
298			functions while building your application.
299
300			=head1 @EXPORT
301
302			ExtUtils::Embed exports the following functions:
303
304			xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
305			ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
306
307			=head1 FUNCTIONS
308
309			=over 4
310
311			=item xsinit()
312
313			Generate C/C++ code for the XS initializer function.
314
315			When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
316			the following options are recognized:
317
318			B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
319
320			B<-o STDOUT> will print to STDOUT.
321
322			B<-std> (Write code for extensions that are linked with the current Perl.)
323
324			Any additional arguments are expected to be names of modules
325			to generate code for.
326
327			When invoked with parameters the following are accepted and optional:
328
329			C<xsinit($filename,$std,[@modules])>
330
331			Where,
332
333			B<$filename> is equivalent to the B<-o> option.
334
335			B<$std> is boolean, equivalent to the B<-std> option.
336
337			B<[@modules]> is an array ref, same as additional arguments mentioned above.
338
339			=item Examples
340
341
342			perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket
343
344
345			This will generate code with an B<xs_init> function that glues the perl B<Socket::bootstrap> function
346			to the C B<boot_Socket> function and writes it to a file named F<xsinit.c>.
347
348			Note that B<DynaLoader> is a special case where it must call B<boot_DynaLoader> directly.
349
350			perl -MExtUtils::Embed -e xsinit
351
352
353			This will generate code for linking with B<DynaLoader> and
354			each static extension found in B<$Config{static_ext}>.
355			The code is written to the default file name B<perlxsi.c>.
356
357
358			perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle
359
360
361			Here, code is written for all the currently linked extensions along with code
362			for B<DBI> and B<DBD::Oracle>.
363
364			If you have a working B<DynaLoader> then there is rarely any need to statically link in any
365			other extensions.
366
367			=item ldopts()
368
369			Output arguments for linking the Perl library and extensions to your
370			application.
371
372			When invoked as C<`perl -MExtUtils::Embed -e ldopts --`>
373			the following options are recognized:
374
375			B<-std>
376
377			Output arguments for linking the Perl library and any extensions linked
378			with the current Perl.
379
380			B<-I> E<lt>path1:path2E<gt>
381
382			Search path for ModuleName.a archives.
383			Default path is B<@INC>.
384			Library archives are expected to be found as
385			B</some/path/auto/ModuleName/ModuleName.a>
386			For example, when looking for B<Socket.a> relative to a search path,
387			we should find B<auto/Socket/Socket.a>
388
389			When looking for B<DBD::Oracle> relative to a search path,
390			we should find B<auto/DBD/Oracle/Oracle.a>
391
392			Keep in mind that you can always supply B</my/own/path/ModuleName.a>
393			as an additional linker argument.
394
395			B<--> E<lt>list of linker argsE<gt>
396
397			Additional linker arguments to be considered.
398
399			Any additional arguments found before the B<--> token
400			are expected to be names of modules to generate code for.
401
402			When invoked with parameters the following are accepted and optional:
403
404			C<ldopts($std,[@modules],[@link_args],$path)>
405
406			Where:
407
408			B<$std> is boolean, equivalent to the B<-std> option.
409
410			B<[@modules]> is equivalent to additional arguments found before the B<--> token.
411
412			B<[@link_args]> is equivalent to arguments found after the B<--> token.
413
414			B<$path> is equivalent to the B<-I> option.
415
416			In addition, when ldopts is called with parameters, it will return the argument string
417			rather than print it to STDOUT.
418
419			=item Examples
420
421
422			perl -MExtUtils::Embed -e ldopts
423
424
425			This will print arguments for linking with B<libperl.a>, B<DynaLoader> and
426			extensions found in B<$Config{static_ext}>. This includes libraries
427			found in B<$Config{libs}> and the first ModuleName.a library
428			for each extension that is found by searching B<@INC> or the path
429			specified by the B<-I> option.
430			In addition, when ModuleName.a is found, additional linker arguments
431			are picked up from the B<extralibs.ld> file in the same directory.
432
433
434			perl -MExtUtils::Embed -e ldopts -- -std Socket
435
436
437			This will do the same as the above example, along with printing additional arguments for linking with the B<Socket> extension.
438
439
440			perl -MExtUtils::Embed -e ldopts -- DynaLoader
441
442
443			This will print arguments for linking with just the B<DynaLoader> extension
444			and B<libperl.a>.
445
446
447			perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql
448
449
450			Any arguments after the second '--' token are additional linker
451			arguments that will be examined for potential conflict. If there is no
452			conflict, the additional arguments will be part of the output.
453
454
455			=item perl_inc()
456
457			For including perl header files this function simply prints:
458
459			-I$Config{archlibexp}/CORE
460
461			So, rather than having to say:
462
463			perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
464
465			Just say:
466
467			perl -MExtUtils::Embed -e perl_inc
468
469			=item ccflags(), ccdlflags()
470
471			These functions simply print $Config{ccflags} and $Config{ccdlflags}
472
473			=item ccopts()
474
475			This function combines perl_inc(), ccflags() and ccdlflags() into one.
476
477			=item xsi_header()
478
479			This function simply returns a string defining the same B<EXTERN_C> macro as
480			B<perlmain.c> along with #including B<perl.h> and B<EXTERN.h>.
481
482			=item xsi_protos(@modules)
483
484			This function returns a string of B<boot_$ModuleName> prototypes for each @modules.
485
486			=item xsi_body(@modules)
487
488			This function returns a string of calls to B<newXS()> that glue the module B<bootstrap>
489			function to B<boot_ModuleName> for each @modules.
490
491			B<xsinit()> uses the xsi_* functions to generate most of its code.
492
493			=back
494
495			=head1 EXAMPLES
496
497			For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
498			with embedded perl, see L<perlembed>.
499
500			=head1 SEE ALSO
501
502			L<perlembed>
503
504			=head1 AUTHOR
505
506			Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
507
508			Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
509			B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.
510
511			=cut
512