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.12_01';
   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 =item have_compiler
 121
 122 Returns true if the current system has a working C compiler and
 123 linker, false otherwise.  To determine this, we actually compile and
 124 link a sample C library.
 125
 126 =item compile
 127
 128 Compiles a C source file and produces an object file.  The name of the
 129 object file is returned.  The source file is specified in a C<source>
 130 parameter, which is required; the other parameters listed below are
 131 optional.
 132
 133 =over 4
 134
 135 =item C<object_file>
 136
 137 Specifies the name of the output file to create.  Otherwise the
 138 C<object_file()> method will be consulted, passing it the name of the
 139 C<source> file.
 140
 141 =item C<include_dirs>
 142
 143 Specifies any additional directories in which to search for header
 144 files.  May be given as a string indicating a single directory, or as
 145 a list reference indicating multiple directories.
 146
 147 =item C<extra_compiler_flags>
 148
 149 Specifies any additional arguments to pass to the compiler.  Should be
 150 given as a list reference containing the arguments individually, or if
 151 this is not possible, as a string containing all the arguments
 152 together.
 153
 154 =back
 155
 156 The operation of this method is also affected by the
 157 C<archlibexp>, C<cccdlflags>, C<ccflags>, C<optimize>, and C<cc>
 158 entries in C<Config.pm>.
 159
 160 =item link
 161
 162 Invokes the linker to produce a library file from object files.  In
 163 scalar context, the name of the library file is returned.  In list
 164 context, the library file and any temporary files created are
 165 returned.  A required C<objects> parameter contains the name of the
 166 object files to process, either in a string (for one object file) or
 167 list reference (for one or more files).  The following parameters are
 168 optional:
 169
 170
 171 =over 4
 172
 173 =item lib_file
 174
 175 Specifies the name of the output library file to create.  Otherwise
 176 the C<lib_file()> method will be consulted, passing it the name of
 177 the first entry in C<objects>.
 178
 179 =item module_name
 180
 181 Specifies the name of the Perl module that will be created by linking.
 182 On platforms that need to do prelinking (Win32, OS/2, etc.) this is a
 183 required parameter.
 184
 185 =item extra_linker_flags
 186
 187 Any additional flags you wish to pass to the linker.
 188
 189 =back
 190
 191 On platforms where C<need_prelink()> returns true, C<prelink()>
 192 will be called automatically.
 193
 194 The operation of this method is also affected by the C<lddlflags>,
 195 C<shrpenv>, and C<ld> entries in C<Config.pm>.
 196
 197 =item link_executable
 198
 199 Invokes the linker to produce an executable file from object files.  In
 200 scalar context, the name of the executable file is returned.  In list
 201 context, the executable file and any temporary files created are
 202 returned.  A required C<objects> parameter contains the name of the
 203 object files to process, either in a string (for one object file) or
 204 list reference (for one or more files).  The optional parameters are
 205 the same as C<link> with exception for
 206
 207
 208 =over 4
 209
 210 =item exe_file
 211
 212 Specifies the name of the output executable file to create.  Otherwise
 213 the C<exe_file()> method will be consulted, passing it the name of the
 214 first entry in C<objects>.
 215
 216 =back
 217
 218 =item object_file
 219
 220  my $object_file = $b->object_file($source_file);
 221
 222 Converts the name of a C source file to the most natural name of an
 223 output object file to create from it.  For instance, on Unix the
 224 source file F<foo.c> would result in the object file F<foo.o>.
 225
 226 =item lib_file
 227
 228  my $lib_file = $b->lib_file($object_file);
 229
 230 Converts the name of an object file to the most natural name of a
 231 output library file to create from it.  For instance, on Mac OS X the
 232 object file F<foo.o> would result in the library file F<foo.bundle>.
 233
 234 =item exe_file
 235
 236  my $exe_file = $b->exe_file($object_file);
 237
 238 Converts the name of an object file to the most natural name of an
 239 executable file to create from it.  For instance, on Mac OS X the
 240 object file F<foo.o> would result in the executable file F<foo>, and
 241 on Windows it would result in F<foo.exe>.
 242
 243
 244 =item prelink
 245
 246 On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
 247 to perform some actions before invoking the linker.  The
 248 C<ExtUtils::Mksymlists> module does this, writing files used by the
 249 linker during the creation of shared libraries for dynamic extensions.
 250 The names of any files written will be returned as a list.
 251
 252 Several parameters correspond to C<ExtUtils::Mksymlists::Mksymlists()>
 253 options, as follows:
 254
 255     Mksymlists()   prelink()          type
 256    -------------|-------------------|-------------------
 257     NAME        |  dl_name          | string (required)
 258     DLBASE      |  dl_base          | string
 259     FILE        |  dl_file          | string
 260     DL_VARS     |  dl_vars          | array reference
 261     DL_FUNCS    |  dl_funcs         | hash reference
 262     FUNCLIST    |  dl_func_list     | array reference
 263     IMPORTS     |  dl_imports       | hash reference
 264
 265 Please see the documentation for C<ExtUtils::Mksymlists> for the
 266 details of what these parameters do.
 267
 268 =item need_prelink
 269
 270 Returns true on platforms where C<prelink()> should be called
 271 during linking, and false otherwise.
 272
 273 =back
 274
 275 =head1 TO DO
 276
 277 Currently this has only been tested on Unix and doesn't contain any of
 278 the Windows-specific code from the C<Module::Build> project.  I'll do
 279 that next.
 280
 281 =head1 HISTORY
 282
 283 This module is an outgrowth of the C<Module::Build> project, to which
 284 there have been many contributors.  Notably, Randy W. Sims submitted
 285 lots of code to support 3 compilers on Windows and helped with various
 286 other platform-specific issues.
 287
 288 =head1 AUTHOR
 289
 290 Ken Williams, kwilliams@cpan.org
 291
 292 =head1 COPYRIGHT
 293
 294 Copyright (c) 2003-2005 Ken Williams.  All rights reserved.
 295
 296 This library is free software; you can redistribute it and/or
 297 modify it under the same terms as Perl itself.
 298
 299 =head1 SEE ALSO
 300
 301 perl(1), Module::Build(3)
 302
 303 =cut