[Summary view] [Print] [Text view]

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