This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
bump ExtUtils-CBuilder version for blead change
[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 ();
6
7use vars qw($VERSION @ISA);
ed6b886e 8$VERSION = '0.280201';
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
15my %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
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.
61my $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
83sub os_type { $OSTYPES{$^O} }
84
851;
86__END__
87
88=head1 NAME
89
90ExtUtils::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
102This module can build the C portions of Perl modules by invoking the
103appropriate compilers and linkers in a cross-platform manner. It was
104motivated by the C<Module::Build> project, but may be useful for other
105purposes as well. However, it is I<not> intended as a general
106cross-platform interface to all your C building needs. That would
107have been a much more ambitious goal!
108
109=head1 METHODS
110
111=over 4
112
113=item new
114
115Returns a new C<ExtUtils::CBuilder> object. A C<config> parameter
116lets you override C<Config.pm> settings for all operations performed
117by 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
123A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
124commands 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
131Returns true if the current system has a working C compiler and
132linker, false otherwise. To determine this, we actually compile and
9015f106
DG
133link a sample C library. The sample will be compiled in the system
134tempdir or, if that fails for some reason, in the current directory.
6b09c160 135
506098d4
DG
136=item have_cplusplus
137
138Just like have_compiler but for C++ instead of C.
139
6b09c160
YST
140=item compile
141
142Compiles a C source file and produces an object file. The name of the
143object file is returned. The source file is specified in a C<source>
144parameter, which is required; the other parameters listed below are
145optional.
146
147=over 4
148
149=item C<object_file>
150
151Specifies the name of the output file to create. Otherwise the
152C<object_file()> method will be consulted, passing it the name of the
153C<source> file.
154
155=item C<include_dirs>
156
157Specifies any additional directories in which to search for header
158files. May be given as a string indicating a single directory, or as
159a list reference indicating multiple directories.
160
161=item C<extra_compiler_flags>
162
163Specifies any additional arguments to pass to the compiler. Should be
164given as a list reference containing the arguments individually, or if
165this is not possible, as a string containing all the arguments
166together.
167
506098d4
DG
168=item C<C++>
169
170Specifies that the source file is a C++ source file and sets appropriate
171compiler flags
172
6b09c160
YST
173=back
174
175The operation of this method is also affected by the
345dbb93 176C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
6b09c160
YST
177entries in C<Config.pm>.
178
179=item link
180
181Invokes the linker to produce a library file from object files. In
182scalar context, the name of the library file is returned. In list
183context, the library file and any temporary files created are
184returned. A required C<objects> parameter contains the name of the
185object files to process, either in a string (for one object file) or
186list reference (for one or more files). The following parameters are
187optional:
188
189
190=over 4
191
192=item lib_file
193
194Specifies the name of the output library file to create. Otherwise
195the C<lib_file()> method will be consulted, passing it the name of
196the first entry in C<objects>.
197
198=item module_name
199
200Specifies the name of the Perl module that will be created by linking.
201On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
202required parameter.
203
204=item extra_linker_flags
205
206Any additional flags you wish to pass to the linker.
207
208=back
209
210On platforms where C<need_prelink()> returns true, C<prelink()>
211will be called automatically.
212
213The operation of this method is also affected by the C<lddlflags>,
214C<shrpenv>, and C<ld> entries in C<Config.pm>.
215
216=item link_executable
217
218Invokes the linker to produce an executable file from object files. In
219scalar context, the name of the executable file is returned. In list
220context, the executable file and any temporary files created are
221returned. A required C<objects> parameter contains the name of the
222object files to process, either in a string (for one object file) or
223list reference (for one or more files). The optional parameters are
224the same as C<link> with exception for
225
226
227=over 4
228
229=item exe_file
230
231Specifies the name of the output executable file to create. Otherwise
232the C<exe_file()> method will be consulted, passing it the name of the
233first entry in C<objects>.
234
235=back
236
237=item object_file
238
239 my $object_file = $b->object_file($source_file);
240
241Converts the name of a C source file to the most natural name of an
242output object file to create from it. For instance, on Unix the
243source file F<foo.c> would result in the object file F<foo.o>.
244
245=item lib_file
246
247 my $lib_file = $b->lib_file($object_file);
248
249Converts the name of an object file to the most natural name of a
250output library file to create from it. For instance, on Mac OS X the
251object file F<foo.o> would result in the library file F<foo.bundle>.
252
253=item exe_file
254
255 my $exe_file = $b->exe_file($object_file);
256
257Converts the name of an object file to the most natural name of an
258executable file to create from it. For instance, on Mac OS X the
259object file F<foo.o> would result in the executable file F<foo>, and
260on Windows it would result in F<foo.exe>.
261
262
263=item prelink
264
265On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
266to perform some actions before invoking the linker. The
267C<ExtUtils::Mksymlists> module does this, writing files used by the
268linker during the creation of shared libraries for dynamic extensions.
269The names of any files written will be returned as a list.
270
271Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
272options, as follows:
273
274 Mksymlists() prelink() type
275 -------------|-------------------|-------------------
276 NAME | dl_name | string (required)
277 DLBASE | dl_base | string
278 FILE | dl_file | string
279 DL_VARS | dl_vars | array reference
280 DL_FUNCS | dl_funcs | hash reference
281 FUNCLIST | dl_func_list | array reference
282 IMPORTS | dl_imports | hash reference
ce87d91c 283 VERSION | dl_version | string
6b09c160
YST
284
285Please see the documentation for C<ExtUtils::Mksymlists> for the
286details of what these parameters do.
287
288=item need_prelink
289
290Returns true on platforms where C<prelink()> should be called
291during linking, and false otherwise.
292
ce87d91c
SP
293=item extra_link_args_after_prelink
294
295Returns list of extra arguments to give to the link command; the arguments
296are the same as for prelink(), with addition of array reference to the
297results of prelink(); this reference is indexed by key C<prelink_res>.
298
6b09c160
YST
299=back
300
301=head1 TO DO
302
303Currently this has only been tested on Unix and doesn't contain any of
304the Windows-specific code from the C<Module::Build> project. I'll do
305that next.
306
307=head1 HISTORY
308
309This module is an outgrowth of the C<Module::Build> project, to which
310there have been many contributors. Notably, Randy W. Sims submitted
311lots of code to support 3 compilers on Windows and helped with various
ce87d91c
SP
312other platform-specific issues. Ilya Zakharevich has contributed
313fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
314for VMS.
6b09c160
YST
315
316=head1 AUTHOR
317
318Ken Williams, kwilliams@cpan.org
319
320=head1 COPYRIGHT
321
322Copyright (c) 2003-2005 Ken Williams. All rights reserved.
323
324This library is free software; you can redistribute it and/or
325modify it under the same terms as Perl itself.
326
327=head1 SEE ALSO
328
329perl(1), Module::Build(3)
330
331=cut