git.maemo.org Git - pkg-perl/blob - deb-src/libextutils-cbuilder-perl/libextutils-cbuilder-perl-0.23/README

   1 NAME
   2     ExtUtils::CBuilder - Compile and link C code for Perl modules
   3
   4 SYNOPSIS
   5       use ExtUtils::CBuilder;
   6
   7       my $b = ExtUtils::CBuilder->new(%options);
   8       $obj_file = $b->compile(source => 'MyModule.c');
   9       $lib_file = $b->link(objects => $obj_file);
  10
  11 DESCRIPTION
  12     This module can build the C portions of Perl modules by invoking the
  13     appropriate compilers and linkers in a cross-platform manner. It was
  14     motivated by the `Module::Build' project, but may be useful for other
  15     purposes as well. However, it is *not* intended as a general
  16     cross-platform interface to all your C building needs. That would have
  17     been a much more ambitious goal!
  18
  19 METHODS
  20     new Returns a new `ExtUtils::CBuilder' object. A `config' parameter lets
  21         you override `Config.pm' settings for all operations performed by
  22         the object, as in the following example:
  23
  24           # Use a different compiler than Config.pm says
  25           my $b = ExtUtils::CBuilder->new( config =>
  26                                            { ld => 'gcc' } );
  27
  28         A `quiet' parameter tells `CBuilder' to not print its `system()'
  29         commands before executing them:
  30
  31           # Be quieter than normal
  32           my $b = ExtUtils::CBuilder->new( quiet => 1 );
  33
  34     have_compiler
  35         Returns true if the current system has a working C compiler and
  36         linker, false otherwise. To determine this, we actually compile and
  37         link a sample C library.
  38
  39     compile
  40         Compiles a C source file and produces an object file. The name of
  41         the object file is returned. The source file is specified in a
  42         `source' parameter, which is required; the other parameters listed
  43         below are optional.
  44
  45         `object_file'
  46             Specifies the name of the output file to create. Otherwise the
  47             `object_file()' method will be consulted, passing it the name of
  48             the `source' file.
  49
  50         `include_dirs'
  51             Specifies any additional directories in which to search for
  52             header files. May be given as a string indicating a single
  53             directory, or as a list reference indicating multiple
  54             directories.
  55
  56         `extra_compiler_flags'
  57             Specifies any additional arguments to pass to the compiler.
  58             Should be given as a list reference containing the arguments
  59             individually, or if this is not possible, as a string containing
  60             all the arguments together.
  61
  62         The operation of this method is also affected by the `archlibexp',
  63         `cccdlflags', `ccflags', `optimize', and `cc' entries in
  64         `Config.pm'.
  65
  66     link
  67         Invokes the linker to produce a library file from object files. In
  68         scalar context, the name of the library file is returned. In list
  69         context, the library file and any temporary files created are
  70         returned. A required `objects' parameter contains the name of the
  71         object files to process, either in a string (for one object file) or
  72         list reference (for one or more files). The following parameters are
  73         optional:
  74
  75         lib_file
  76             Specifies the name of the output library file to create.
  77             Otherwise the `lib_file()' method will be consulted, passing it
  78             the name of the first entry in `objects'.
  79
  80         module_name
  81             Specifies the name of the Perl module that will be created by
  82             linking. On platforms that need to do prelinking (Win32, OS/2,
  83             etc.) this is a required parameter.
  84
  85         extra_linker_flags
  86             Any additional flags you wish to pass to the linker.
  87
  88         On platforms where `need_prelink()' returns true, `prelink()' will
  89         be called automatically.
  90
  91         The operation of this method is also affected by the `lddlflags',
  92         `shrpenv', and `ld' entries in `Config.pm'.
  93
  94     link_executable
  95         Invokes the linker to produce an executable file from object files.
  96         In scalar context, the name of the executable file is returned. In
  97         list context, the executable file and any temporary files created
  98         are returned. A required `objects' parameter contains the name of
  99         the object files to process, either in a string (for one object
 100         file) or list reference (for one or more files). The optional
 101         parameters are the same as `link' with exception for
 102
 103         exe_file
 104             Specifies the name of the output executable file to create.
 105             Otherwise the `exe_file()' method will be consulted, passing it
 106             the name of the first entry in `objects'.
 107
 108     object_file
 109          my $object_file = $b->object_file($source_file);
 110
 111         Converts the name of a C source file to the most natural name of an
 112         output object file to create from it. For instance, on Unix the
 113         source file foo.c would result in the object file foo.o.
 114
 115     lib_file
 116          my $lib_file = $b->lib_file($object_file);
 117
 118         Converts the name of an object file to the most natural name of a
 119         output library file to create from it. For instance, on Mac OS X the
 120         object file foo.o would result in the library file foo.bundle.
 121
 122     exe_file
 123          my $exe_file = $b->exe_file($object_file);
 124
 125         Converts the name of an object file to the most natural name of an
 126         executable file to create from it. For instance, on Mac OS X the
 127         object file foo.o would result in the executable file foo, and on
 128         Windows it would result in foo.exe.
 129
 130     prelink
 131         On certain platforms like Win32, OS/2, VMS, and AIX, it is necessary
 132         to perform some actions before invoking the linker. The
 133         `ExtUtils::Mksymlists' module does this, writing files used by the
 134         linker during the creation of shared libraries for dynamic
 135         extensions. The names of any files written will be returned as a
 136         list.
 137
 138         Several parameters correspond to
 139         `ExtUtils::Mksymlists::Mksymlists()' options, as follows:
 140
 141             Mksymlists()   prelink()          type
 142            -------------|-------------------|-------------------
 143             NAME        |  dl_name          | string (required)
 144             DLBASE      |  dl_base          | string
 145             FILE        |  dl_file          | string
 146             DL_VARS     |  dl_vars          | array reference
 147             DL_FUNCS    |  dl_funcs         | hash reference
 148             FUNCLIST    |  dl_func_list     | array reference
 149             IMPORTS     |  dl_imports       | hash reference
 150             VERSION     |  dl_version       | string
 151
 152         Please see the documentation for `ExtUtils::Mksymlists' for the
 153         details of what these parameters do.
 154
 155     need_prelink
 156         Returns true on platforms where `prelink()' should be called during
 157         linking, and false otherwise.
 158
 159     extra_link_args_after_prelink
 160         Returns list of extra arguments to give to the link command; the
 161         arguments are the same as for prelink(), with addition of array
 162         reference to the results of prelink(); this reference is indexed by
 163         key `prelink_res'.
 164
 165 TO DO
 166     Currently this has only been tested on Unix and doesn't contain any of
 167     the Windows-specific code from the `Module::Build' project. I'll do that
 168     next.
 169
 170 HISTORY
 171     This module is an outgrowth of the `Module::Build' project, to which
 172     there have been many contributors. Notably, Randy W. Sims submitted lots
 173     of code to support 3 compilers on Windows and helped with various other
 174     platform-specific issues. Ilya Zakharevich has contributed fixes for
 175     OS/2; John E. Malmberg and Peter Prymmer have done likewise for VMS.
 176
 177 AUTHOR
 178     Ken Williams, kwilliams@cpan.org
 179
 180 COPYRIGHT
 181     Copyright (c) 2003-2005 Ken Williams. All rights reserved.
 182
 183     This library is free software; you can redistribute it and/or modify it
 184     under the same terms as Perl itself.
 185
 186 SEE ALSO
 187     perl(1), Module::Build(3)
 188