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