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