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