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