dist/ExtUtils-CBuilder/lib/ExtUtils/CBuilder.pm

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