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