[perl5.git] / 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
Commit	Line	Data
39234879	1	# $Id: Embed.pm,v 1.1.1.1 2002/01/16 19:27:19 schwern Exp $
a2c6f8f1	2	require 5.002;
	3
	4	package ExtUtils::Embed;
	5	require Exporter;
	6	require FileHandle;
	7	use Config;
	8	use Getopt::Std;
9bbedd82	9	use File::Spec;
a2c6f8f1	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
39234879	21	$VERSION = 1.2506_01;
a2c6f8f1	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
7e24002c DM	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
a2c6f8f1	47	sub xsinit {
	48	my($file, $std, $mods) = @_;
	49	my($fh,@mods,%seen);
	50	$file \|\|= "perlxsi.c";
acfe0abc	51	my $xsinit_proto = "pTHX";
a2c6f8f1	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();
20ce7b12	75	print $fh "EXTERN_C void xs_init ($xsinit_proto);\n\n";
a2c6f8f1	76	print $fh &xsi_protos(@mods);
a2c6f8f1	77
8bdb6b78	78	print $fh "\nEXTERN_C void\nxs_init($xsinit_proto)\n{\n";
a2c6f8f1	79	print $fh &xsi_body(@mods);
	80	print $fh "}\n";
	81
	82	}
	83
	84	sub xsi_header {
	85	return <<EOF;
a2c6f8f1	86	#include <EXTERN.h>
a2c6f8f1	87	#include <perl.h>
a2c6f8f1	88
	89	EOF
	90	}
	91
	92	sub xsi_protos {
	93	my(@exts) = @_;
	94	my(@retval,%seen);
acfe0abc	95	my $boot_proto = "pTHX_ CV* cv";
a2c6f8f1	96	foreach $_ (@exts){
	97	my($pname) = canon('/', $_);
	98	my($mname, $cname);
	99	($mname = $pname) =~ s!/!::!g;
	100	($cname = $pname) =~ s!/!__!g;
20ce7b12	101	my($ccode) = "EXTERN_C void boot_${cname} ($boot_proto);\n";
a2c6f8f1	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');
a3c8358c	112	push(@retval, "\tchar *file = __FILE__;\n");
a2c6f8f1	113	push(@retval, "\tdXSUB_SYS;\n") if $] > 5.002;
a3c8358c	114	push(@retval, "\n");
a2c6f8f1	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
03f2ffd8 JH	142	sub _escape {
	143	my $arg = shift;
	144	$$arg =~ s/([\(\)])/\\$1/g;
	145	}
	146
f0595bdd JH	147	sub _ldflags {
f0595bdd JH	148	my $ldflags = $Config{ldflags};
03f2ffd8	149	_escape(\$ldflags);
f0595bdd JH	150	return $ldflags;
	151	}
	152
	153	sub _ccflags {
	154	my $ccflags = $Config{ccflags};
03f2ffd8	155	_escape(\$ccflags);
f0595bdd JH	156	return $ccflags;
	157	}
	158
	159	sub _ccdlflags {
	160	my $ccdlflags = $Config{ccdlflags};
03f2ffd8	161	_escape(\$ccdlflags);
f0595bdd JH	162	return $ccdlflags;
	163	}
	164
a2c6f8f1	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 ' ';
a2c6f8f1	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;
9bbedd82 JH	187	my $sep = $Config{path_sep} \|\| ':';
9bbedd82 JH	188	@path = $path ? split(/\Q$sep/, $path) : @INC;
a2c6f8f1	189
a2c6f8f1	190	push(@potential_libs, @link_args) if scalar @link_args;
9bbedd82 JH	191	# makemaker includes std libs on windows by default
	192	if ($^O ne 'MSWin32' and defined($std)) {
	193	push(@potential_libs, $Config{perllibs});
	194	}
a2c6f8f1	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) {
3ab83790	201	@ns = split(/::\|\/\|\\/, $mod);
a2c6f8f1	202	$sub = $ns[-1];
56c2fb36	203	$root = File::Spec->catdir(@ns);
a2c6f8f1	204
	205	print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
	206	foreach (@path) {
56c2fb36	207	next unless -e ($archive = File::Spec->catdir($_,"auto",$root,"$sub$lib_ext"));
a2c6f8f1	208	push @archives, $archive;
56c2fb36	209	if(-e ($extra = File::Spec->catdir($_,"auto",$root,"extralibs.ld"))) {
a2c6f8f1	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
9bbedd82 JH	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	}
af248097	231
9bbedd82 JH	232	my $lpath = File::Spec->catdir($Config{archlibexp}, 'CORE');
9bbedd82 JH	233	$lpath = qq["$lpath"] if $^O eq 'MSWin32';
a2c6f8f1	234	my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
5de3f0da	235	MM->ext(join ' ', "-L$lpath", $libperl, @potential_libs);
a2c6f8f1	236
	237	my $ld_or_bs = $bsloadlibs \|\| $ldloadlibs;
	238	print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
f0595bdd JH	239	my $ccdlflags = _ccdlflags();
	240	my $ldflags = _ldflags();
	241	my $linkage = "$ccdlflags $ldflags @archives $ld_or_bs";
a2c6f8f1	242	print STDERR "ldopts: '$linkage'\n" if $Verbose;
	243
	244	return $linkage if scalar @_;
7e24002c	245	my_return("$linkage\n");
a2c6f8f1	246	}
	247
	248	sub ccflags {
f0595bdd JH	249	my $ccflags = _ccflags();
f0595bdd JH	250	my_return(" $ccflags ");
a2c6f8f1	251	}
	252
	253	sub ccdlflags {
f0595bdd JH	254	my $ccdlflags = _ccdlflags();
f0595bdd JH	255	my_return(" $ccdlflags ");
a2c6f8f1	256	}
	257
	258	sub perl_inc {
9bbedd82 JH	259	my $dir = File::Spec->catdir($Config{archlibexp}, 'CORE');
	260	$dir = qq["$dir"] if $^O eq 'MSWin32';
	261	my_return(" -I$dir ");
a2c6f8f1	262	}
	263
	264	sub ccopts {
7e24002c	265	ccflags . perl_inc;
a2c6f8f1	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
9bbedd82	290	perl -MExtUtils::Embed -e ccopts
a2c6f8f1	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:
a6006777	303
4e864201 JM	304	xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(),
4e864201 JM	305	ccdlflags(), xsi_header(), xsi_protos(), xsi_body()
a2c6f8f1	306
	307	=head1 FUNCTIONS
	308
bbc7dcd2	309	=over 4
2ae324a7	310
a2c6f8f1	311	=item xsinit()
a2c6f8f1	312
4e864201	313	Generate C/C++ code for the XS initializer function.
a2c6f8f1	314
	315	When invoked as C<`perl -MExtUtils::Embed -e xsinit --`>
	316	the following options are recognized:
	317
4e864201	318	B<-o> E<lt>output filenameE<gt> (Defaults to B<perlxsi.c>)
a2c6f8f1	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
a6006777	341
a2c6f8f1	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
a7665c5e	346	to the C B<boot_Socket> function and writes it to a file named F<xsinit.c>.
a2c6f8f1	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
4e864201	380	B<-I> E<lt>path1:path2E<gt>
a2c6f8f1	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
a7665c5e	392	Keep in mind that you can always supply B</my/own/path/ModuleName.a>
a2c6f8f1	393	as an additional linker argument.
a2c6f8f1	394
4e864201	395	B<--> E<lt>list of linker argsE<gt>
a2c6f8f1	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
a7665c5e	406	Where:
a2c6f8f1	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
de592821	429	specified by the B<-I> option.
a2c6f8f1	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
a6006777	435
a2c6f8f1	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
36477c24	459	-I$Config{archlibexp}/CORE
a2c6f8f1	460
	461	So, rather than having to say:
	462
36477c24	463	perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'
a2c6f8f1	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
022735b4	491	B<xsinit()> uses the xsi_* functions to generate most of its code.
a2c6f8f1	492
2ae324a7	493	=back
2ae324a7	494
a2c6f8f1	495	=head1 EXAMPLES
	496
	497	For examples on how to use B<ExtUtils::Embed> for building C/C++ applications
0325b4c4	498	with embedded perl, see L<perlembed>.
a6006777	499
a2c6f8f1	500	=head1 SEE ALSO
a2c6f8f1	501
4e864201	502	L<perlembed>
a2c6f8f1	503
	504	=head1 AUTHOR
	505
4e864201	506	Doug MacEachern E<lt>F<dougm@osf.org>E<gt>
a2c6f8f1	507
4e864201 JM	508	Based on ideas from Tim Bunce E<lt>F<Tim.Bunce@ig.co.uk>E<gt> and
4e864201 JM	509	B<minimod.pl> by Andreas Koenig E<lt>F<k@anna.in-berlin.de>E<gt> and Tim Bunce.
a2c6f8f1	510
	511	=cut
	512