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