1 package ExtUtils::CBuilder;
7 use vars qw($VERSION @ISA);
9 $VERSION = eval $VERSION;
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.
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.
66 my @package = split /::/, __PACKAGE__;
68 if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) {
69 $load->(__PACKAGE__ . "::Platform::$^O");
71 } elsif (exists $OSTYPES{$^O} and
72 grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) {
73 $load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}");
76 $load->(__PACKAGE__ . "::Base");
80 sub os_type { $OSTYPES{$^O} }
87 ExtUtils::CBuilder - Compile and link C code for Perl modules
91 use ExtUtils::CBuilder;
93 my $b = ExtUtils::CBuilder->new(%options);
94 $obj_file = $b->compile(source => 'MyModule.c');
95 $lib_file = $b->link(objects => $obj_file);
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!
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:
116 # Use a different compiler than Config.pm says
117 my $b = ExtUtils::CBuilder->new( config =>
122 Returns true if the current system has a working C compiler and
123 linker, false otherwise. To determine this, we actually compile and
124 link a sample C library.
128 Compiles a C source file and produces an object file. The name of the
129 object file is returned. The source file is specified in a C<source>
130 parameter, which is required; the other parameters listed below are
137 Specifies the name of the output file to create. Otherwise the
138 C<object_file()> method will be consulted, passing it the name of the
141 =item C<include_dirs>
143 Specifies any additional directories in which to search for header
144 files. May be given as a string indicating a single directory, or as
145 a list reference indicating multiple directories.
147 =item C<extra_compiler_flags>
149 Specifies any additional arguments to pass to the compiler. Should be
150 given as a list reference containing the arguments individually, or if
151 this is not possible, as a string containing all the arguments
156 The operation of this method is also affected by the
157 C<installarchlib>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
158 entries in C<Config.pm>.
162 Invokes the linker to produce a library file from object files. In
163 scalar context, the name of the library file is returned. In list
164 context, the library file and any temporary files created are
165 returned. A required C<objects> parameter contains the name of the
166 object files to process, either in a string (for one object file) or
167 list reference (for one or more files). The following parameters are
175 Specifies the name of the output library file to create. Otherwise
176 the C<lib_file()> method will be consulted, passing it the name of
177 the first entry in C<objects>.
181 Specifies the name of the Perl module that will be created by linking.
182 On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
185 =item extra_linker_flags
187 Any additional flags you wish to pass to the linker.
191 On platforms where C<need_prelink()> returns true, C<prelink()>
192 will be called automatically.
194 The operation of this method is also affected by the C<lddlflags>,
195 C<shrpenv>, and C<ld> entries in C<Config.pm>.
197 =item link_executable
199 Invokes the linker to produce an executable file from object files. In
200 scalar context, the name of the executable file is returned. In list
201 context, the executable file and any temporary files created are
202 returned. A required C<objects> parameter contains the name of the
203 object files to process, either in a string (for one object file) or
204 list reference (for one or more files). The optional parameters are
205 the same as C<link> with exception for
212 Specifies the name of the output executable file to create. Otherwise
213 the C<exe_file()> method will be consulted, passing it the name of the
214 first entry in C<objects>.
220 my $object_file = $b->object_file($source_file);
222 Converts the name of a C source file to the most natural name of an
223 output object file to create from it. For instance, on Unix the
224 source file F<foo.c> would result in the object file F<foo.o>.
228 my $lib_file = $b->lib_file($object_file);
230 Converts the name of an object file to the most natural name of a
231 output library file to create from it. For instance, on Mac OS X the
232 object file F<foo.o> would result in the library file F<foo.bundle>.
236 my $exe_file = $b->exe_file($object_file);
238 Converts the name of an object file to the most natural name of an
239 executable file to create from it. For instance, on Mac OS X the
240 object file F<foo.o> would result in the executable file F<foo>, and
241 on Windows it would result in F<foo.exe>.
246 On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
247 to perform some actions before invoking the linker. The
248 C<ExtUtils::Mksymlists> module does this, writing files used by the
249 linker during the creation of shared libraries for dynamic extensions.
250 The names of any files written will be returned as a list.
252 Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
255 Mksymlists() prelink() type
256 -------------|-------------------|-------------------
257 NAME | dl_name | string (required)
258 DLBASE | dl_base | string
259 FILE | dl_file | string
260 DL_VARS | dl_vars | array reference
261 DL_FUNCS | dl_funcs | hash reference
262 FUNCLIST | dl_func_list | array reference
263 IMPORTS | dl_imports | hash reference
265 Please see the documentation for C<ExtUtils::Mksymlists> for the
266 details of what these parameters do.
270 Returns true on platforms where C<prelink()> should be called
271 during linking, and false otherwise.
277 Currently this has only been tested on Unix and doesn't contain any of
278 the Windows-specific code from the C<Module::Build> project. I'll do
283 This module is an outgrowth of the C<Module::Build> project, to which
284 there have been many contributors. Notably, Randy W. Sims submitted
285 lots of code to support 3 compilers on Windows and helped with various
286 other platform-specific issues.
290 Ken Williams, kwilliams@cpan.org
294 Copyright (c) 2003-2005 Ken Williams. All rights reserved.
296 This library is free software; you can redistribute it and/or
297 modify it under the same terms as Perl itself.
301 perl(1), Module::Build(3)