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 =>
120 A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
121 commands before executing them:
123 # Be quieter than normal
124 my $b = ExtUtils::CBuilder->new( quiet => 1 );
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.
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
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
147 =item C<include_dirs>
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.
153 =item C<extra_compiler_flags>
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
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>.
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
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>.
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
191 =item extra_linker_flags
193 Any additional flags you wish to pass to the linker.
197 On platforms where C<need_prelink()> returns true, C<prelink()>
198 will be called automatically.
200 The operation of this method is also affected by the C<lddlflags>,
201 C<shrpenv>, and C<ld> entries in C<Config.pm>.
203 =item link_executable
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
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>.
226 my $object_file = $b->object_file($source_file);
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>.
234 my $lib_file = $b->lib_file($object_file);
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>.
242 my $exe_file = $b->exe_file($object_file);
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>.
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.
258 Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
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
272 Please see the documentation for C<ExtUtils::Mksymlists> for the
273 details of what these parameters do.
277 Returns true on platforms where C<prelink()> should be called
278 during linking, and false otherwise.
280 =item extra_link_args_after_prelink
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>.
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
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
305 Ken Williams, kwilliams@cpan.org
309 Copyright (c) 2003-2005 Ken Williams. All rights reserved.
311 This library is free software; you can redistribute it and/or
312 modify it under the same terms as Perl itself.
316 perl(1), Module::Build(3)