[p5sagit/p5-mst-13.2.git] / lib / ExtUtils / Embed.pm

# $Id: Embed.pm,v 1.2501 $
require 5.002;

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

#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 = sprintf("%d.%02d", q$Revision: 1.2505 $ =~ /(\d+)\.(\d+)/);

@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 is_perl_object {
    $Config{ccflags} =~ /-DPERL_OBJECT/;  
}

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

    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;
#if defined(__cplusplus) && !defined(PERL_OBJECT)
#define is_cplusplus
#endif

#ifdef is_cplusplus
extern "C" {
#endif

#include <EXTERN.h>
#include <perl.h>
#ifdef PERL_OBJECT
#define NO_XSLOCKS
#include <XSUB.h>
#include "win32iop.h"
#include <fcntl.h>
#include <perlhost.h>
#endif
#ifdef is_cplusplus
}
#  ifndef EXTERN_C
#    define EXTERN_C extern "C"
#  endif
#else
#  ifndef EXTERN_C
#    define EXTERN_C extern
#  endif
#endif

EOF
}    

sub xsi_protos {
    my(@exts) = @_;
    my(@retval,%seen);
    my $boot_proto = is_perl_object() ? 
	"CV* cv _CPERLarg" : "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 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 ' ';
    my $MM = bless {} => 'MY';
    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;
    @path = $path ? split(/:/, $path) : @INC;

    push(@potential_libs, @link_args)    if scalar @link_args;
    push(@potential_libs, $Config{libs}) if defined $std;

    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 = $MM->catdir(@ns);
	
	print STDERR "searching for '$sub${lib_ext}'\n" if $Verbose;
	foreach (@path) {
	    next unless -e ($archive = $MM->catdir($_,"auto",$root,"$sub$lib_ext"));
	    push @archives, $archive;
	    if(-e ($extra = $MM->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 = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";

    my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
	$MM->ext(join ' ', 
		 $MM->catdir("-L$Config{archlibexp}", "CORE"), " $libperl", 
		 @potential_libs);

    my $ld_or_bs = $bsloadlibs || $ldloadlibs;
    print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
    my $linkage = "$Config{ccdlflags} $Config{ldflags} @archives $ld_or_bs";
    print STDERR "ldopts: '$linkage'\n" if $Verbose;

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

sub ccflags {
    my_return(" $Config{ccflags} ");
}

sub ccdlflags {
    my_return(" $Config{ccdlflags} ");
}

sub perl_inc {
    my_return(" -I$Config{archlibexp}/CORE ");
}

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 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

=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 "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, 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 
specifed 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 it's code.

=back

=head1 EXAMPLES

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