local-lib5/man/man3/ExtUtils::CBuilder.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ExtUtils::CBuilder 3"
 132 .TH ExtUtils::CBuilder 3 "2009-10-30" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::CBuilder \- Compile and link C code for Perl modules
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use ExtUtils::CBuilder;
 139 .Ve
 140 .PP
 141 .Vb 3
 142 \&  my $b = ExtUtils::CBuilder\->new(%options);
 143 \&  $obj_file = $b\->compile(source => 'MyModule.c');
 144 \&  $lib_file = $b\->link(objects => $obj_file);
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 This module can build the C portions of Perl modules by invoking the
 149 appropriate compilers and linkers in a cross-platform manner.  It was
 150 motivated by the \f(CW\*(C`Module::Build\*(C'\fR project, but may be useful for other
 151 purposes as well.  However, it is \fInot\fR intended as a general
 152 cross-platform interface to all your C building needs.  That would
 153 have been a much more ambitious goal!
 154 .SH "METHODS"
 155 .IX Header "METHODS"
 156 .IP "new" 4
 157 .IX Item "new"
 158 Returns a new \f(CW\*(C`ExtUtils::CBuilder\*(C'\fR object.  A \f(CW\*(C`config\*(C'\fR parameter
 159 lets you override \f(CW\*(C`Config.pm\*(C'\fR settings for all operations performed
 160 by the object, as in the following example:
 161 .Sp
 162 .Vb 3
 163 \&  # Use a different compiler than Config.pm says
 164 \&  my $b = ExtUtils::CBuilder\->new( config =>
 165 \&                                   { ld => 'gcc' } );
 166 .Ve
 167 .Sp
 168 A \f(CW\*(C`quiet\*(C'\fR parameter tells \f(CW\*(C`CBuilder\*(C'\fR to not print its \f(CW\*(C`system()\*(C'\fR
 169 commands before executing them:
 170 .Sp
 171 .Vb 2
 172 \&  # Be quieter than normal
 173 \&  my $b = ExtUtils::CBuilder\->new( quiet => 1 );
 174 .Ve
 175 .IP "have_compiler" 4
 176 .IX Item "have_compiler"
 177 Returns true if the current system has a working C compiler and
 178 linker, false otherwise.  To determine this, we actually compile and
 179 link a sample C library.  The sample will be compiled in the system
 180 tempdir or, if that fails for some reason, in the current directory.
 181 .IP "have_cplusplus" 4
 182 .IX Item "have_cplusplus"
 183 Just like have_compiler but for \*(C+ instead of C.
 184 .IP "compile" 4
 185 .IX Item "compile"
 186 Compiles a C source file and produces an object file.  The name of the
 187 object file is returned.  The source file is specified in a \f(CW\*(C`source\*(C'\fR
 188 parameter, which is required; the other parameters listed below are
 189 optional.
 190 .RS 4
 191 .ie n .IP """object_file""" 4
 192 .el .IP "\f(CWobject_file\fR" 4
 193 .IX Item "object_file"
 194 Specifies the name of the output file to create.  Otherwise the
 195 \&\f(CW\*(C`object_file()\*(C'\fR method will be consulted, passing it the name of the
 196 \&\f(CW\*(C`source\*(C'\fR file.
 197 .ie n .IP """include_dirs""" 4
 198 .el .IP "\f(CWinclude_dirs\fR" 4
 199 .IX Item "include_dirs"
 200 Specifies any additional directories in which to search for header
 201 files.  May be given as a string indicating a single directory, or as
 202 a list reference indicating multiple directories.
 203 .ie n .IP """extra_compiler_flags""" 4
 204 .el .IP "\f(CWextra_compiler_flags\fR" 4
 205 .IX Item "extra_compiler_flags"
 206 Specifies any additional arguments to pass to the compiler.  Should be
 207 given as a list reference containing the arguments individually, or if
 208 this is not possible, as a string containing all the arguments
 209 together.
 210 .ie n .IP """C++""" 4
 211 .el .IP "\f(CWC++\fR" 4
 212 .IX Item "C++"
 213 Specifies that the source file is a \*(C+ source file and sets appropriate
 214 compiler flags
 215 .RE
 216 .RS 4
 217 .Sp
 218 The operation of this method is also affected by the
 219 \&\f(CW\*(C`archlibexp\*(C'\fR, \f(CW\*(C`cccdlflags\*(C'\fR, \f(CW\*(C`ccflags\*(C'\fR, \f(CW\*(C`optimize\*(C'\fR, and \f(CW\*(C`cc\*(C'\fR
 220 entries in \f(CW\*(C`Config.pm\*(C'\fR.
 221 .RE
 222 .IP "link" 4
 223 .IX Item "link"
 224 Invokes the linker to produce a library file from object files.  In
 225 scalar context, the name of the library file is returned.  In list
 226 context, the library file and any temporary files created are
 227 returned.  A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
 228 object files to process, either in a string (for one object file) or
 229 list reference (for one or more files).  The following parameters are
 230 optional:
 231 .RS 4
 232 .IP "lib_file" 4
 233 .IX Item "lib_file"
 234 Specifies the name of the output library file to create.  Otherwise
 235 the \f(CW\*(C`lib_file()\*(C'\fR method will be consulted, passing it the name of
 236 the first entry in \f(CW\*(C`objects\*(C'\fR.
 237 .IP "module_name" 4
 238 .IX Item "module_name"
 239 Specifies the name of the Perl module that will be created by linking.
 240 On platforms that need to do prelinking (Win32, \s-1OS/2\s0, etc.) this is a
 241 required parameter.
 242 .IP "extra_linker_flags" 4
 243 .IX Item "extra_linker_flags"
 244 Any additional flags you wish to pass to the linker.
 245 .RE
 246 .RS 4
 247 .Sp
 248 On platforms where \f(CW\*(C`need_prelink()\*(C'\fR returns true, \f(CW\*(C`prelink()\*(C'\fR
 249 will be called automatically.
 250 .Sp
 251 The operation of this method is also affected by the \f(CW\*(C`lddlflags\*(C'\fR,
 252 \&\f(CW\*(C`shrpenv\*(C'\fR, and \f(CW\*(C`ld\*(C'\fR entries in \f(CW\*(C`Config.pm\*(C'\fR.
 253 .RE
 254 .IP "link_executable" 4
 255 .IX Item "link_executable"
 256 Invokes the linker to produce an executable file from object files.  In
 257 scalar context, the name of the executable file is returned.  In list
 258 context, the executable file and any temporary files created are
 259 returned.  A required \f(CW\*(C`objects\*(C'\fR parameter contains the name of the
 260 object files to process, either in a string (for one object file) or
 261 list reference (for one or more files).  The optional parameters are
 262 the same as \f(CW\*(C`link\*(C'\fR with exception for
 263 .RS 4
 264 .IP "exe_file" 4
 265 .IX Item "exe_file"
 266 Specifies the name of the output executable file to create.  Otherwise
 267 the \f(CW\*(C`exe_file()\*(C'\fR method will be consulted, passing it the name of the
 268 first entry in \f(CW\*(C`objects\*(C'\fR.
 269 .RE
 270 .RS 4
 271 .RE
 272 .IP "object_file" 4
 273 .IX Item "object_file"
 274 .Vb 1
 275 \& my $object_file = $b\->object_file($source_file);
 276 .Ve
 277 .Sp
 278 Converts the name of a C source file to the most natural name of an
 279 output object file to create from it.  For instance, on Unix the
 280 source file \fIfoo.c\fR would result in the object file \fIfoo.o\fR.
 281 .IP "lib_file" 4
 282 .IX Item "lib_file"
 283 .Vb 1
 284 \& my $lib_file = $b\->lib_file($object_file);
 285 .Ve
 286 .Sp
 287 Converts the name of an object file to the most natural name of a
 288 output library file to create from it.  For instance, on Mac \s-1OS\s0 X the
 289 object file \fIfoo.o\fR would result in the library file \fIfoo.bundle\fR.
 290 .IP "exe_file" 4
 291 .IX Item "exe_file"
 292 .Vb 1
 293 \& my $exe_file = $b\->exe_file($object_file);
 294 .Ve
 295 .Sp
 296 Converts the name of an object file to the most natural name of an
 297 executable file to create from it.  For instance, on Mac \s-1OS\s0 X the
 298 object file \fIfoo.o\fR would result in the executable file \fIfoo\fR, and
 299 on Windows it would result in \fIfoo.exe\fR.
 300 .IP "prelink" 4
 301 .IX Item "prelink"
 302 On certain platforms like Win32, \s-1OS/2\s0, \s-1VMS\s0, and \s-1AIX\s0, it is necessary
 303 to perform some actions before invoking the linker.  The
 304 \&\f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR module does this, writing files used by the
 305 linker during the creation of shared libraries for dynamic extensions.
 306 The names of any files written will be returned as a list.
 307 .Sp
 308 Several parameters correspond to \f(CW\*(C`ExtUtils::Mksymlists::Mksymlists()\*(C'\fR
 309 options, as follows:
 310 .Sp
 311 .Vb 10
 312 \&    Mksymlists()   prelink()          type
 313 \&   \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 314 \&    NAME        |  dl_name          | string (required)
 315 \&    DLBASE      |  dl_base          | string
 316 \&    FILE        |  dl_file          | string
 317 \&    DL_VARS     |  dl_vars          | array reference
 318 \&    DL_FUNCS    |  dl_funcs         | hash reference
 319 \&    FUNCLIST    |  dl_func_list     | array reference
 320 \&    IMPORTS     |  dl_imports       | hash reference
 321 \&    VERSION     |  dl_version       | string
 322 .Ve
 323 .Sp
 324 Please see the documentation for \f(CW\*(C`ExtUtils::Mksymlists\*(C'\fR for the
 325 details of what these parameters do.
 326 .IP "need_prelink" 4
 327 .IX Item "need_prelink"
 328 Returns true on platforms where \f(CW\*(C`prelink()\*(C'\fR should be called
 329 during linking, and false otherwise.
 330 .IP "extra_link_args_after_prelink" 4
 331 .IX Item "extra_link_args_after_prelink"
 332 Returns list of extra arguments to give to the link command; the arguments
 333 are the same as for \fIprelink()\fR, with addition of array reference to the
 334 results of \fIprelink()\fR; this reference is indexed by key \f(CW\*(C`prelink_res\*(C'\fR.
 335 .SH "TO DO"
 336 .IX Header "TO DO"
 337 Currently this has only been tested on Unix and doesn't contain any of
 338 the Windows-specific code from the \f(CW\*(C`Module::Build\*(C'\fR project.  I'll do
 339 that next.
 340 .SH "HISTORY"
 341 .IX Header "HISTORY"
 342 This module is an outgrowth of the \f(CW\*(C`Module::Build\*(C'\fR project, to which
 343 there have been many contributors.  Notably, Randy W. Sims submitted
 344 lots of code to support 3 compilers on Windows and helped with various
 345 other platform-specific issues.  Ilya Zakharevich has contributed
 346 fixes for \s-1OS/2\s0; John E. Malmberg and Peter Prymmer have done likewise
 347 for \s-1VMS\s0.
 348 .SH "AUTHOR"
 349 .IX Header "AUTHOR"
 350 Ken Williams, kwilliams@cpan.org
 351 .SH "COPYRIGHT"
 352 .IX Header "COPYRIGHT"
 353 Copyright (c) 2003\-2005 Ken Williams.  All rights reserved.
 354 .PP
 355 This library is free software; you can redistribute it and/or
 356 modify it under the same terms as Perl itself.
 357 .SH "SEE ALSO"
 358 .IX Header "SEE ALSO"
 359 \&\fIperl\fR\|(1), \fIModule::Build\fR\|(3)