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