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
   7 use vars qw($VERSION @ISA);
   8 $VERSION = '0.280202';
   9 $VERSION = eval $VERSION;
  10
  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.
  14
  15 my %OSTYPES = qw(
  16                  aix       Unix
  17                  bsdos     Unix
  18                  dgux      Unix
  19                  dynixptx  Unix
  20                  freebsd   Unix
  21                  linux     Unix
  22                  hpux      Unix
  23                  irix      Unix
  24                  darwin    Unix
  25                  machten   Unix
  26                  next      Unix
  27                  openbsd   Unix
  28                  netbsd    Unix
  29                  dec_osf   Unix
  30                  svr4      Unix
  31                  svr5      Unix
  32                  sco_sv    Unix
  33                  unicos    Unix
  34                  unicosmk  Unix
  35                  solaris   Unix
  36                  sunos     Unix
  37                  cygwin    Unix
  38                  os2       Unix
  39                  gnu       Unix
  40                  gnukfreebsd Unix
  41                  haiku     Unix
  42
  43                  dos       Windows
  44                  MSWin32   Windows
  45
  46                  os390     EBCDIC
  47                  os400     EBCDIC
  48                  posix-bc  EBCDIC
  49                  vmesa     EBCDIC
  50
  51                  MacOS     MacOS
  52                  VMS       VMS
  53                  VOS       VOS
  54                  riscos    RiscOS
  55                  amigaos   Amiga
  56                  mpeix     MPEiX
  57                 );
  58
  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.
  61 my $load = sub {
  62   my $mod = shift;
  63   eval "use $mod";
  64   die $@ if $@;
  65   @ISA = ($mod);
  66 };
  67
  68 {
  69   my @package = split /::/, __PACKAGE__;
  70
  71   if (grep {-e File::Spec->catfile($_, @package, 'Platform', $^O) . '.pm'} @INC) {
  72     $load->(__PACKAGE__ . "::Platform::$^O");
  73
  74   } elsif (exists $OSTYPES{$^O} and
  75            grep {-e File::Spec->catfile($_, @package, 'Platform', $OSTYPES{$^O}) . '.pm'} @INC) {
  76     $load->(__PACKAGE__ . "::Platform::$OSTYPES{$^O}");
  77
  78   } else {
  79     $load->(__PACKAGE__ . "::Base");
  80   }
  81 }
  82
  83 sub os_type { $OSTYPES{$^O} }
  84
  85 1;
  86 __END__
  87
  88 =head1 NAME
  89
  90 ExtUtils::CBuilder - Compile and link C code for Perl modules
  91
  92 =head1 SYNOPSIS
  93
  94   use ExtUtils::CBuilder;
  95
  96   my $b = ExtUtils::CBuilder->new(%options);
  97   $obj_file = $b->compile(source => 'MyModule.c');
  98   $lib_file = $b->link(objects => $obj_file);
  99
 100 =head1 DESCRIPTION
 101
 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!
 108
 109 =head1 METHODS
 110
 111 =over 4
 112
 113 =item new
 114
 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:
 118
 119   # Use a different compiler than Config.pm says
 120   my $b = ExtUtils::CBuilder->new( config =>
 121                                    { ld => 'gcc' } );
 122
 123 A C<quiet> parameter tells C<CBuilder> to not print its C<system()>
 124 commands before executing them:
 125
 126   # Be quieter than normal
 127   my $b = ExtUtils::CBuilder->new( quiet => 1 );
 128
 129 =item have_compiler
 130
 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.
 135
 136 =item have_cplusplus
 137
 138 Just like have_compiler but for C++ instead of C.
 139
 140 =item compile
 141
 142 Compiles a C source file and produces an object file.  The name of the
 143 object file is returned.  The source file is specified in a C<source>
 144 parameter, which is required; the other parameters listed below are
 145 optional.
 146
 147 =over 4
 148
 149 =item C<object_file>
 150
 151 Specifies the name of the output file to create.  Otherwise the
 152 C<object_file()> method will be consulted, passing it the name of the
 153 C<source> file.
 154
 155 =item C<include_dirs>
 156
 157 Specifies any additional directories in which to search for header
 158 files.  May be given as a string indicating a single directory, or as
 159 a list reference indicating multiple directories.
 160
 161 =item C<extra_compiler_flags>
 162
 163 Specifies any additional arguments to pass to the compiler.  Should be
 164 given as a list reference containing the arguments individually, or if
 165 this is not possible, as a string containing all the arguments
 166 together.
 167
 168 =item C<C++>
 169
 170 Specifies that the source file is a C++ source file and sets appropriate
 171 compiler flags
 172
 173 =back
 174
 175 The operation of this method is also affected by the
 176 C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
 177 entries in C<Config.pm>.
 178
 179 =item link
 180
 181 Invokes the linker to produce a library file from object files.  In
 182 scalar context, the name of the library file is returned.  In list
 183 context, the library file and any temporary files created are
 184 returned.  A required C<objects> parameter contains the name of the
 185 object files to process, either in a string (for one object file) or
 186 list reference (for one or more files).  The following parameters are
 187 optional:
 188
 189
 190 =over 4
 191
 192 =item lib_file
 193
 194 Specifies the name of the output library file to create.  Otherwise
 195 the C<lib_file()> method will be consulted, passing it the name of
 196 the first entry in C<objects>.
 197
 198 =item module_name
 199
 200 Specifies the name of the Perl module that will be created by linking.
 201 On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
 202 required parameter.
 203
 204 =item extra_linker_flags
 205
 206 Any additional flags you wish to pass to the linker.
 207
 208 =back
 209
 210 On platforms where C<need_prelink()> returns true, C<prelink()>
 211 will be called automatically.
 212
 213 The operation of this method is also affected by the C<lddlflags>,
 214 C<shrpenv>, and C<ld> entries in C<Config.pm>.
 215
 216 =item link_executable
 217
 218 Invokes the linker to produce an executable file from object files.  In
 219 scalar context, the name of the executable file is returned.  In list
 220 context, the executable file and any temporary files created are
 221 returned.  A required C<objects> parameter contains the name of the
 222 object files to process, either in a string (for one object file) or
 223 list reference (for one or more files).  The optional parameters are
 224 the same as C<link> with exception for
 225
 226
 227 =over 4
 228
 229 =item exe_file
 230
 231 Specifies the name of the output executable file to create.  Otherwise
 232 the C<exe_file()> method will be consulted, passing it the name of the
 233 first entry in C<objects>.
 234
 235 =back
 236
 237 =item object_file
 238
 239  my $object_file = $b->object_file($source_file);
 240
 241 Converts the name of a C source file to the most natural name of an
 242 output object file to create from it.  For instance, on Unix the
 243 source file F<foo.c> would result in the object file F<foo.o>.
 244
 245 =item lib_file
 246
 247  my $lib_file = $b->lib_file($object_file);
 248
 249 Converts the name of an object file to the most natural name of a
 250 output library file to create from it.  For instance, on Mac OS X the
 251 object file F<foo.o> would result in the library file F<foo.bundle>.
 252
 253 =item exe_file
 254
 255  my $exe_file = $b->exe_file($object_file);
 256
 257 Converts the name of an object file to the most natural name of an
 258 executable file to create from it.  For instance, on Mac OS X the
 259 object file F<foo.o> would result in the executable file F<foo>, and
 260 on Windows it would result in F<foo.exe>.
 261
 262
 263 =item prelink
 264
 265 On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
 266 to perform some actions before invoking the linker.  The
 267 C<ExtUtils::Mksymlists> module does this, writing files used by the
 268 linker during the creation of shared libraries for dynamic extensions.
 269 The names of any files written will be returned as a list.
 270
 271 Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
 272 options, as follows:
 273
 274     Mksymlists()   prelink()          type
 275    -------------|-------------------|-------------------
 276     NAME        |  dl_name          | string (required)
 277     DLBASE      |  dl_base          | string
 278     FILE        |  dl_file          | string
 279     DL_VARS     |  dl_vars          | array reference
 280     DL_FUNCS    |  dl_funcs         | hash reference
 281     FUNCLIST    |  dl_func_list     | array reference
 282     IMPORTS     |  dl_imports       | hash reference
 283     VERSION     |  dl_version       | string
 284
 285 Please see the documentation for C<ExtUtils::Mksymlists> for the
 286 details of what these parameters do.
 287
 288 =item need_prelink
 289
 290 Returns true on platforms where C<prelink()> should be called
 291 during linking, and false otherwise.
 292
 293 =item extra_link_args_after_prelink
 294
 295 Returns list of extra arguments to give to the link command; the arguments
 296 are the same as for prelink(), with addition of array reference to the
 297 results of prelink(); this reference is indexed by key C<prelink_res>.
 298
 299 =back
 300
 301 =head1 TO DO
 302
 303 Currently this has only been tested on Unix and doesn't contain any of
 304 the Windows-specific code from the C<Module::Build> project.  I'll do
 305 that next.
 306
 307 =head1 HISTORY
 308
 309 This module is an outgrowth of the C<Module::Build> project, to which
 310 there have been many contributors.  Notably, Randy W. Sims submitted
 311 lots of code to support 3 compilers on Windows and helped with various
 312 other platform-specific issues.  Ilya Zakharevich has contributed
 313 fixes for OS/2; John E. Malmberg and Peter Prymmer have done likewise
 314 for VMS.
 315
 316 =head1 AUTHOR
 317
 318 Ken Williams, kwilliams@cpan.org
 319
 320 =head1 COPYRIGHT
 321
 322 Copyright (c) 2003-2005 Ken Williams.  All rights reserved.
 323
 324 This library is free software; you can redistribute it and/or
 325 modify it under the same terms as Perl itself.
 326
 327 =head1 SEE ALSO
 328
 329 perl(1), Module::Build(3)
 330
 331 =cut