[perl5.git] / cpan / ExtUtils-CBuilder / lib / ExtUtils / CBuilder.pm

package ExtUtils::CBuilder;

use File::Spec ();
use File::Path ();
use File::Basename ();

use vars qw($VERSION @ISA);
$VERSION = '0.260301';
$VERSION = eval $VERSION;

# Okay, this is the brute-force method of finding out what kind of
# platform we're on.  I don't know of a systematic way.  These values
# came from the latest (bleadperl) perlport.pod.

my %OSTYPES = qw(
		 aix       Unix
		 bsdos     Unix
		 dgux      Unix
		 dynixptx  Unix
		 freebsd   Unix
		 linux     Unix
		 hpux      Unix
		 irix      Unix
		 darwin    Unix
		 machten   Unix
		 next      Unix
		 openbsd   Unix
		 netbsd    Unix
		 dec_osf   Unix
		 svr4      Unix
		 svr5      Unix
		 sco_sv    Unix
		 unicos    Unix
		 unicosmk  Unix
		 solaris   Unix
		 sunos     Unix
		 cygwin    Unix
		 os2       Unix
		 gnu       Unix
		 gnukfreebsd Unix
		 haiku     Unix
		 
		 dos       Windows
		 MSWin32   Windows

		 os390     EBCDIC
		 os400     EBCDIC
		 posix-bc  EBCDIC
		 vmesa     EBCDIC

		 MacOS     MacOS
		 VMS       VMS
		 VOS       VOS
		 riscos    RiscOS
		 amigaos   Amiga
		 mpeix     MPEiX
		);

# We only use this once - don't waste a symbol table entry on it.
# More importantly, don't make it an inheritable method.
my $load = sub {
  my $mod = shift;
  eval "use $mod";
  die $@ if $@;
  @ISA = ($mod);
};

{
  my @package = split /::/, __PACKAGE__;
  
  if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) {
    $load->(__PACKAGE__ . "::Platform::$^O");
    
  } elsif (exists $OSTYPES{$^O} and
	   grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) {
    $load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}");
    
  } else {
    $load->(__PACKAGE__ . "::Base");
  }
}

sub os_type { $OSTYPES{$^O} }

1;
__END__

=head1 NAME

ExtUtils::CBuilder - Compile and link C code for Perl modules

=head1 SYNOPSIS

  use ExtUtils::CBuilder;

  my $b = ExtUtils::CBuilder->new(%options);
  $obj_file = $b->compile(source => 'MyModule.c');
  $lib_file = $b->link(objects => $obj_file);

=head1 DESCRIPTION

This module can build the C portions of Perl modules by invoking the
appropriate compilers and linkers in a cross-platform manner.  It was
motivated by the C<Module::Build> project, but may be useful for other
purposes as well.  However, it is I<not> intended as a general
cross-platform interface to all your C building needs.  That would
have been a much more ambitious goal!

=head1 METHODS

=over 4

=item new

Returns a new C<ExtUtils::CBuilder> object.  A C<config> parameter
lets you override C<Config.pm> settings for all operations performed
by the object, as in the following example:

  # Use a different compiler than Config.pm says
  my $b = ExtUtils::CBuilder->new( config =>
                                   { ld => 'gcc' } );

A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
commands before executing them:

  # Be quieter than normal
  my $b = ExtUtils::CBuilder->new( quiet => 1 );

=item have_compiler

Returns true if the current system has a working C compiler and
linker, false otherwise.  To determine this, we actually compile and
link a sample C library.  The sample will be compiled in the system
tempdir or, if that fails for some reason, in the current directory.

=item compile

Compiles a C source file and produces an object file.  The name of the
object file is returned.  The source file is specified in a C<source>
parameter, which is required; the other parameters listed below are
optional.

=over 4

=item C<object_file>

Specifies the name of the output file to create.  Otherwise the
C<object_file()> method will be consulted, passing it the name of the
C<source> file.

=item C<include_dirs>

Specifies any additional directories in which to search for header
files.  May be given as a string indicating a single directory, or as
a list reference indicating multiple directories.

=item C<extra_compiler_flags>

Specifies any additional arguments to pass to the compiler.  Should be
given as a list reference containing the arguments individually, or if
this is not possible, as a string containing all the arguments
together.

=back

The operation of this method is also affected by the
C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
entries in C<Config.pm>.

=item link

Invokes the linker to produce a library file from object files.  In
scalar context, the name of the library file is returned.  In list
context, the library file and any temporary files created are
returned.  A required C<objects> parameter contains the name of the
object files to process, either in a string (for one object file) or
list reference (for one or more files).  The following parameters are
optional:


=over 4

=item lib_file

Specifies the name of the output library file to create.  Otherwise
the C<lib_file()> method will be consulted, passing it the name of
the first entry in C<objects>.

=item module_name

Specifies the name of the Perl module that will be created by linking.
On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
required parameter.

=item extra_linker_flags

Any additional flags you wish to pass to the linker.

=back

On platforms where C<need_prelink()> returns true, C<prelink()>
will be called automatically.

The operation of this method is also affected by the C<lddlflags>,
C<shrpenv>, and C<ld> entries in C<Config.pm>.

=item link_executable

Invokes the linker to produce an executable file from object files.  In
scalar context, the name of the executable file is returned.  In list
context, the executable file and any temporary files created are
returned.  A required C<objects> parameter contains the name of the
object files to process, either in a string (for one object file) or
list reference (for one or more files).  The optional parameters are
the same as C<link> with exception for


=over 4

=item exe_file

Specifies the name of the output executable file to create.  Otherwise
the C<exe_file()> method will be consulted, passing it the name of the
first entry in C<objects>.

=back

=item object_file

 my $object_file = $b->object_file($source_file);

Converts the name of a C source file to the most natural name of an
output object file to create from it.  For instance, on Unix the
source file F<foo.c> would result in the object file F<foo.o>.

=item lib_file

 my $lib_file = $b->lib_file($object_file);

Converts the name of an object file to the most natural name of a
output library file to create from it.  For instance, on Mac OS X the
object file F<foo.o> would result in the library file F<foo.bundle>.

=item exe_file

 my $exe_file = $b->exe_file($object_file);

Converts the name of an object file to the most natural name of an
executable file to create from it.  For instance, on Mac OS X the
object file F<foo.o> would result in the executable file F<foo>, and
on Windows it would result in F<foo.exe>.


=item prelink

On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
to perform some actions before invoking the linker.  The
C<ExtUtils::Mksymlists> module does this, writing files used by the
linker during the creation of shared libraries for dynamic extensions.
The names of any files written will be returned as a list.

Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
options, as follows:

    Mksymlists()   prelink()          type
   -------------|-------------------|-------------------
    NAME        |  dl_name          | string (required)
    DLBASE      |  dl_base          | string
    FILE        |  dl_file          | string
    DL_VARS     |  dl_vars          | array reference
    DL_FUNCS    |  dl_funcs         | hash reference
    FUNCLIST    |  dl_func_list     | array reference
    IMPORTS     |  dl_imports       | hash reference
    VERSION     |  dl_version       | string

Please see the documentation for C<ExtUtils::Mksymlists> for the
details of what these parameters do.

=item need_prelink

Returns true on platforms where C<prelink()> should be called
during linking, and false otherwise.

=item extra_link_args_after_prelink

Returns list of extra arguments to give to the link command; the arguments
are the same as for prelink(), with addition of array reference to the
results of prelink(); this reference is indexed by key C<prelink_res>.

=back

=head1 TO DO

Currently this has only been tested on Unix and doesn't contain any of
the Windows-specific code from the C<Module::Build> project.  I'll do
that next.

=head1 HISTORY

This module is an outgrowth of the C<Module::Build> project, to which
there have been many contributors.  Notably, Randy W. Sims submitted
lots of code to support 3 compilers on Windows and helped with various
other platform-specific issues.  Ilya Zakharevich has contributed
fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
for VMS.

=head1 AUTHOR

Ken Williams, kwilliams@cpan.org

=head1 COPYRIGHT

Copyright (c) 2003-2005 Ken Williams.  All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 SEE ALSO

perl(1), Module::Build(3)

=cut
Commit	Line	Data
6b09c160 YST	1	package ExtUtils::CBuilder;
	2
	3	use File::Spec ();
	4	use File::Path ();
	5	use File::Basename ();
	6
	7	use vars qw($VERSION @ISA);
3698b7be	8	$VERSION = '0.260301';
6b09c160 YST	9	$VERSION = eval $VERSION;
	10
	11	# Okay, this is the brute-force method of finding out what kind of
	12	# platform we're on. I don't know of a systematic way. These values
	13	# came from the latest (bleadperl) perlport.pod.
	14
	15	my %OSTYPES = qw(
	16	aix Unix
	17	bsdos Unix
	18	dgux Unix
	19	dynixptx Unix
	20	freebsd Unix
	21	linux Unix
	22	hpux Unix
	23	irix Unix
	24	darwin Unix
	25	machten Unix
	26	next Unix
	27	openbsd Unix
	28	netbsd Unix
	29	dec_osf Unix
	30	svr4 Unix
	31	svr5 Unix
	32	sco_sv Unix
	33	unicos Unix
	34	unicosmk Unix
	35	solaris Unix
	36	sunos Unix
	37	cygwin Unix
	38	os2 Unix
92760223 NC	39	gnu Unix
92760223 NC	40	gnukfreebsd Unix
df00ff3b	41	haiku Unix
6b09c160 YST	42
	43	dos Windows
	44	MSWin32 Windows
	45
	46	os390 EBCDIC
	47	os400 EBCDIC
	48	posix-bc EBCDIC
	49	vmesa EBCDIC
	50
	51	MacOS MacOS
	52	VMS VMS
	53	VOS VOS
	54	riscos RiscOS
	55	amigaos Amiga
	56	mpeix MPEiX
	57	);
	58
	59	# We only use this once - don't waste a symbol table entry on it.
	60	# More importantly, don't make it an inheritable method.
	61	my $load = sub {
	62	my $mod = shift;
	63	eval "use $mod";
	64	die $@ if $@;
	65	@ISA = ($mod);
	66	};
	67
	68	{
	69	my @package = split /::/, __PACKAGE__;
	70
	71	if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) {
	72	$load->(__PACKAGE__ . "::Platform::$^O");
	73
	74	} elsif (exists $OSTYPES{$^O} and
	75	grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) {
	76	$load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}");
	77
	78	} else {
	79	$load->(__PACKAGE__ . "::Base");
	80	}
	81	}
	82
	83	sub os_type { $OSTYPES{$^O} }
	84
	85	1;
	86	__END__
	87
	88	=head1 NAME
	89
	90	ExtUtils::CBuilder - Compile and link C code for Perl modules
	91
	92	=head1 SYNOPSIS
	93
	94	use ExtUtils::CBuilder;
	95
	96	my $b = ExtUtils::CBuilder->new(%options);
	97	$obj_file = $b->compile(source => 'MyModule.c');
	98	$lib_file = $b->link(objects => $obj_file);
	99
	100	=head1 DESCRIPTION
	101
	102	This module can build the C portions of Perl modules by invoking the
	103	appropriate compilers and linkers in a cross-platform manner. It was
	104	motivated by the C<Module::Build> project, but may be useful for other
	105	purposes as well. However, it is I<not> intended as a general
106	cross-platform interface to all your C building needs. That would
107	have been a much more ambitious goal!
108
109	=head1 METHODS
110
111	=over 4
112
113	=item new
114
115	Returns a new C<ExtUtils::CBuilder> object. A C<config> parameter
116	lets you override C<Config.pm> settings for all operations performed
117	by the object, as in the following example:
118
119	# Use a different compiler than Config.pm says
120	my $b = ExtUtils::CBuilder->new( config =>
121	{ ld => 'gcc' } );
122
ea2e6518 RGS	123	A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
	124	commands before executing them:
	125
	126	# Be quieter than normal
	127	my $b = ExtUtils::CBuilder->new( quiet => 1 );
	128
6b09c160 YST	129	=item have_compiler
	130
	131	Returns true if the current system has a working C compiler and
	132	linker, false otherwise. To determine this, we actually compile and
9015f106 DG	133	link a sample C library. The sample will be compiled in the system
9015f106 DG	134	tempdir or, if that fails for some reason, in the current directory.
6b09c160 YST	135
	136	=item compile
	137
	138	Compiles a C source file and produces an object file. The name of the
	139	object file is returned. The source file is specified in a C<source>
	140	parameter, which is required; the other parameters listed below are
	141	optional.
	142
	143	=over 4
	144
	145	=item C<object_file>
	146
	147	Specifies the name of the output file to create. Otherwise the
	148	C<object_file()> method will be consulted, passing it the name of the
	149	C<source> file.
	150
	151	=item C<include_dirs>
	152
	153	Specifies any additional directories in which to search for header
	154	files. May be given as a string indicating a single directory, or as
	155	a list reference indicating multiple directories.
	156
	157	=item C<extra_compiler_flags>
	158
	159	Specifies any additional arguments to pass to the compiler. Should be
	160	given as a list reference containing the arguments individually, or if
	161	this is not possible, as a string containing all the arguments
	162	together.
	163
	164	=back
	165
	166	The operation of this method is also affected by the
345dbb93	167	C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
6b09c160 YST	168	entries in C<Config.pm>.
	169
	170	=item link
	171
	172	Invokes the linker to produce a library file from object files. In
	173	scalar context, the name of the library file is returned. In list
	174	context, the library file and any temporary files created are
	175	returned. A required C<objects> parameter contains the name of the
	176	object files to process, either in a string (for one object file) or
	177	list reference (for one or more files). The following parameters are
	178	optional:
	179
	180
	181	=over 4
	182
	183	=item lib_file
	184
	185	Specifies the name of the output library file to create. Otherwise
	186	the C<lib_file()> method will be consulted, passing it the name of
	187	the first entry in C<objects>.
	188
	189	=item module_name
	190
	191	Specifies the name of the Perl module that will be created by linking.
	192	On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
	193	required parameter.
	194
	195	=item extra_linker_flags
	196
	197	Any additional flags you wish to pass to the linker.
	198
	199	=back
	200
	201	On platforms where C<need_prelink()> returns true, C<prelink()>
	202	will be called automatically.
	203
	204	The operation of this method is also affected by the C<lddlflags>,
	205	C<shrpenv>, and C<ld> entries in C<Config.pm>.
	206
	207	=item link_executable
	208
	209	Invokes the linker to produce an executable file from object files. In
	210	scalar context, the name of the executable file is returned. In list
	211	context, the executable file and any temporary files created are
	212	returned. A required C<objects> parameter contains the name of the
	213	object files to process, either in a string (for one object file) or
	214	list reference (for one or more files). The optional parameters are
	215	the same as C<link> with exception for
	216
	217
	218	=over 4
	219
	220	=item exe_file
	221
	222	Specifies the name of the output executable file to create. Otherwise
	223	the C<exe_file()> method will be consulted, passing it the name of the
	224	first entry in C<objects>.
	225
	226	=back
	227
	228	=item object_file
	229
	230	my $object_file = $b->object_file($source_file);
	231
232	Converts the name of a C source file to the most natural name of an
233	output object file to create from it. For instance, on Unix the
234	source file F<foo.c> would result in the object file F<foo.o>.
235
236	=item lib_file
237
238	my $lib_file = $b->lib_file($object_file);
239
240	Converts the name of an object file to the most natural name of a
241	output library file to create from it. For instance, on Mac OS X the
242	object file F<foo.o> would result in the library file F<foo.bundle>.
243
244	=item exe_file
245
246	my $exe_file = $b->exe_file($object_file);
247
248	Converts the name of an object file to the most natural name of an
249	executable file to create from it. For instance, on Mac OS X the
250	object file F<foo.o> would result in the executable file F<foo>, and
251	on Windows it would result in F<foo.exe>.
252
253
254	=item prelink
255
256	On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
257	to perform some actions before invoking the linker. The
258	C<ExtUtils::Mksymlists> module does this, writing files used by the
259	linker during the creation of shared libraries for dynamic extensions.
260	The names of any files written will be returned as a list.
261
262	Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
263	options, as follows:
264
265	Mksymlists() prelink() type
266	-------------\|-------------------\|-------------------
267	NAME \| dl_name \| string (required)
268	DLBASE \| dl_base \| string
269	FILE \| dl_file \| string
270	DL_VARS \| dl_vars \| array reference
271	DL_FUNCS \| dl_funcs \| hash reference
272	FUNCLIST \| dl_func_list \| array reference
273	IMPORTS \| dl_imports \| hash reference
ce87d91c	274	VERSION \| dl_version \| string
6b09c160 YST	275
	276	Please see the documentation for C<ExtUtils::Mksymlists> for the
	277	details of what these parameters do.
	278
	279	=item need_prelink
	280
	281	Returns true on platforms where C<prelink()> should be called
	282	during linking, and false otherwise.
	283
ce87d91c SP	284	=item extra_link_args_after_prelink
	285
	286	Returns list of extra arguments to give to the link command; the arguments
	287	are the same as for prelink(), with addition of array reference to the
	288	results of prelink(); this reference is indexed by key C<prelink_res>.
	289
6b09c160 YST	290	=back
	291
	292	=head1 TO DO
	293
	294	Currently this has only been tested on Unix and doesn't contain any of
	295	the Windows-specific code from the C<Module::Build> project. I'll do
	296	that next.
	297
	298	=head1 HISTORY
	299
	300	This module is an outgrowth of the C<Module::Build> project, to which
	301	there have been many contributors. Notably, Randy W. Sims submitted
	302	lots of code to support 3 compilers on Windows and helped with various
ce87d91c SP	303	other platform-specific issues. Ilya Zakharevich has contributed
	304	fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
	305	for VMS.
6b09c160 YST	306
	307	=head1 AUTHOR
	308
	309	Ken Williams, kwilliams@cpan.org
	310
	311	=head1 COPYRIGHT
	312
	313	Copyright (c) 2003-2005 Ken Williams. All rights reserved.
	314
	315	This library is free software; you can redistribute it and/or
	316	modify it under the same terms as Perl itself.
	317
	318	=head1 SEE ALSO
	319
	320	perl(1), Module::Build(3)
	321
	322	=cut