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