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