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

package ExtUtils::CBuilder;

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

use vars qw($VERSION @ISA);
$VERSION = '0.15';
$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
		 
		 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' } );

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

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