home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / ExtUtils / CBuilder.pm next >
Encoding:
Perl POD Document  |  2009-06-26  |  8.8 KB  |  321 lines
  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.          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
  321.