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.
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.
69 my @package = split /::/, __PACKAGE__;
71 if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) {
72 $load->(__PACKAGE__ . "::Platform::$^O");
74 } elsif (exists $OSTYPES{$^O} and
75 grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) {
76 $load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}");
79 $load->(__PACKAGE__ . "::Base");
83 sub os_type { $OSTYPES{$^O} }
90 ExtUtils::CBuilder - Compile and link C code for Perl modules
94 use ExtUtils::CBuilder;
96 my $b = ExtUtils::CBuilder->new(%options);
97 $obj_file = $b->compile(source => 'MyModule.c');
98 $lib_file = $b->link(objects => $obj_file);
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!
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:
119 # Use a different compiler than Config.pm says
120 my $b = ExtUtils::CBuilder->new( config =>
123 A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
124 commands before executing them:
126 # Be quieter than normal
127 my $b = ExtUtils::CBuilder->new( quiet => 1 );
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.
138 Compiles a C source file and produces an object file. The name of the
139 object file is returned. The source file is specified in a C<source>
140 parameter, which is required; the other parameters listed below are
147 Specifies the name of the output file to create. Otherwise the
148 C<object_file()> method will be consulted, passing it the name of the
151 =item C<include_dirs>
153 Specifies any additional directories in which to search for header
154 files. May be given as a string indicating a single directory, or as
155 a list reference indicating multiple directories.
157 =item C<extra_compiler_flags>
159 Specifies any additional arguments to pass to the compiler. Should be
160 given as a list reference containing the arguments individually, or if
161 this is not possible, as a string containing all the arguments
166 The operation of this method is also affected by the
167 C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
168 entries in C<Config.pm>.
172 Invokes the linker to produce a library file from object files. In
173 scalar context, the name of the library file is returned. In list
174 context, the library file and any temporary files created are
175 returned. A required C<objects> parameter contains the name of the
176 object files to process, either in a string (for one object file) or
177 list reference (for one or more files). The following parameters are
185 Specifies the name of the output library file to create. Otherwise
186 the C<lib_file()> method will be consulted, passing it the name of
187 the first entry in C<objects>.
191 Specifies the name of the Perl module that will be created by linking.
192 On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
195 =item extra_linker_flags
197 Any additional flags you wish to pass to the linker.
201 On platforms where C<need_prelink()> returns true, C<prelink()>
202 will be called automatically.
204 The operation of this method is also affected by the C<lddlflags>,
205 C<shrpenv>, and C<ld> entries in C<Config.pm>.
207 =item link_executable
209 Invokes the linker to produce an executable file from object files. In
210 scalar context, the name of the executable file is returned. In list
211 context, the executable file and any temporary files created are
212 returned. A required C<objects> parameter contains the name of the
213 object files to process, either in a string (for one object file) or
214 list reference (for one or more files). The optional parameters are
215 the same as C<link> with exception for
222 Specifies the name of the output executable file to create. Otherwise
223 the C<exe_file()> method will be consulted, passing it the name of the
224 first entry in C<objects>.
230 my $object_file = $b->object_file($source_file);
232 Converts the name of a C source file to the most natural name of an
233 output object file to create from it. For instance, on Unix the
234 source file F<foo.c> would result in the object file F<foo.o>.
238 my $lib_file = $b->lib_file($object_file);
240 Converts the name of an object file to the most natural name of a
241 output library file to create from it. For instance, on Mac OS X the
242 object file F<foo.o> would result in the library file F<foo.bundle>.
246 my $exe_file = $b->exe_file($object_file);
248 Converts the name of an object file to the most natural name of an
249 executable file to create from it. For instance, on Mac OS X the
250 object file F<foo.o> would result in the executable file F<foo>, and
251 on Windows it would result in F<foo.exe>.
256 On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
257 to perform some actions before invoking the linker. The
258 C<ExtUtils::Mksymlists> module does this, writing files used by the
259 linker during the creation of shared libraries for dynamic extensions.
260 The names of any files written will be returned as a list.
262 Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
265 Mksymlists() prelink() type
266 -------------|-------------------|-------------------
267 NAME | dl_name | string (required)
268 DLBASE | dl_base | string
269 FILE | dl_file | string
270 DL_VARS | dl_vars | array reference
271 DL_FUNCS | dl_funcs | hash reference
272 FUNCLIST | dl_func_list | array reference
273 IMPORTS | dl_imports | hash reference
274 VERSION | dl_version | string
276 Please see the documentation for C<ExtUtils::Mksymlists> for the
277 details of what these parameters do.
281 Returns true on platforms where C<prelink()> should be called
282 during linking, and false otherwise.
284 =item extra_link_args_after_prelink
286 Returns list of extra arguments to give to the link command; the arguments
287 are the same as for prelink(), with addition of array reference to the
288 results of prelink(); this reference is indexed by key C<prelink_res>.
294 Currently this has only been tested on Unix and doesn't contain any of
295 the Windows-specific code from the C<Module::Build> project. I'll do
300 This module is an outgrowth of the C<Module::Build> project, to which
301 there have been many contributors. Notably, Randy W. Sims submitted
302 lots of code to support 3 compilers on Windows and helped with various
303 other platform-specific issues. Ilya Zakharevich has contributed
304 fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
309 Ken Williams, kwilliams@cpan.org
313 Copyright (c) 2003-2005 Ken Williams. All rights reserved.
315 This library is free software; you can redistribute it and/or
316 modify it under the same terms as Perl itself.
320 perl(1), Module::Build(3)