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