local-lib5/man/man3/ExtUtils::Liblist.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::Liblist 3"
 132 .TH ExtUtils::Liblist 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::Liblist \- determine libraries to use and how to use them
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  require ExtUtils::Liblist;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&  $MM\->ext($potential_libs, $verbose, $need_names);
 143 .Ve
 144 .PP
 145 .Vb 2
 146 \&  # Usually you can get away with:
 147 \&  ExtUtils::Liblist\->ext($potential_libs, $verbose, $need_names)
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 This utility takes a list of libraries in the form \f(CW\*(C`\-llib1 \-llib2
 152 \&\-llib3\*(C'\fR and returns lines suitable for inclusion in an extension
 153 Makefile.  Extra library paths may be included with the form
 154 \&\f(CW\*(C`\-L/another/path\*(C'\fR this will affect the searches for all subsequent
 155 libraries.
 156 .PP
 157 It returns an array of four or five scalar values: \s-1EXTRALIBS\s0,
 158 \&\s-1BSLOADLIBS\s0, \s-1LDLOADLIBS\s0, \s-1LD_RUN_PATH\s0, and, optionally, a reference to
 159 the array of the filenames of actual libraries.  Some of these don't
 160 mean anything unless on Unix.  See the details about those platform
 161 specifics below.  The list of the filenames is returned only if
 162 \&\f(CW$need_names\fR argument is true.
 163 .PP
 164 Dependent libraries can be linked in one of three ways:
 165 .IP "* For static extensions" 2
 166 .IX Item "For static extensions"
 167 by the ld command when the perl binary is linked with the extension
 168 library. See \s-1EXTRALIBS\s0 below.
 169 .IP "* For dynamic extensions at build/link time" 2
 170 .IX Item "For dynamic extensions at build/link time"
 171 by the ld command when the shared object is built/linked. See
 172 \&\s-1LDLOADLIBS\s0 below.
 173 .IP "* For dynamic extensions at load time" 2
 174 .IX Item "For dynamic extensions at load time"
 175 by the DynaLoader when the shared object is loaded. See \s-1BSLOADLIBS\s0
 176 below.
 177 .Sh "\s-1EXTRALIBS\s0"
 178 .IX Subsection "EXTRALIBS"
 179 List of libraries that need to be linked with when linking a perl
 180 binary which includes this extension. Only those libraries that
 181 actually exist are included.  These are written to a file and used
 182 when linking perl.
 183 .Sh "\s-1LDLOADLIBS\s0 and \s-1LD_RUN_PATH\s0"
 184 .IX Subsection "LDLOADLIBS and LD_RUN_PATH"
 185 List of those libraries which can or must be linked into the shared
 186 library when created using ld. These may be static or dynamic
 187 libraries.  \s-1LD_RUN_PATH\s0 is a colon separated list of the directories
 188 in \s-1LDLOADLIBS\s0. It is passed as an environment variable to the process
 189 that links the shared library.
 190 .Sh "\s-1BSLOADLIBS\s0"
 191 .IX Subsection "BSLOADLIBS"
 192 List of those libraries that are needed but can be linked in
 193 dynamically at run time on this platform.  SunOS/Solaris does not need
 194 this because ld records the information (from \s-1LDLOADLIBS\s0) into the
 195 object file.  This list is used to create a .bs (bootstrap) file.
 196 .SH "PORTABILITY"
 197 .IX Header "PORTABILITY"
 198 This module deals with a lot of system dependencies and has quite a
 199 few architecture specific \f(CW\*(C`if\*(C'\fRs in the code.
 200 .Sh "\s-1VMS\s0 implementation"
 201 .IX Subsection "VMS implementation"
 202 The version of \fIext()\fR which is executed under \s-1VMS\s0 differs from the
 203 Unix\-OS/2 version in several respects:
 204 .IP "\(bu" 2
 205 Input library and path specifications are accepted with or without the
 206 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers.  If neither prefix is
 207 present, a token is considered a directory to search if it is in fact
 208 a directory, and a library to search for otherwise.  Authors who wish
 209 their extensions to be portable to Unix or \s-1OS/2\s0 should use the Unix
 210 prefixes, since the Unix\-OS/2 version of \fIext()\fR requires them.
 211 .IP "\(bu" 2
 212 Wherever possible, shareable images are preferred to object libraries,
 213 and object libraries to plain object files.  In accordance with \s-1VMS\s0
 214 naming conventions, \fIext()\fR looks for files named \fIlib\fRshr and \fIlib\fRrtl;
 215 it also looks for \fIlib\fRlib and lib\fIlib\fR to accommodate Unix conventions
 216 used in some ported software.
 217 .IP "\(bu" 2
 218 For each library that is found, an appropriate directive for a linker options
 219 file is generated.  The return values are space-separated strings of
 220 these directives, rather than elements used on the linker command line.
 221 .IP "\(bu" 2
 222 \&\s-1LDLOADLIBS\s0 contains both the libraries found based on \f(CW$potential_libs\fR and
 223 the CRTLs, if any, specified in Config.pm.  \s-1EXTRALIBS\s0 contains just those
 224 libraries found based on \f(CW$potential_libs\fR.  \s-1BSLOADLIBS\s0 and \s-1LD_RUN_PATH\s0
 225 are always empty.
 226 .PP
 227 In addition, an attempt is made to recognize several common Unix library
 228 names, and filter them out or convert them to their \s-1VMS\s0 equivalents, as
 229 appropriate.
 230 .PP
 231 In general, the \s-1VMS\s0 version of \fIext()\fR should properly handle input from
 232 extensions originally designed for a Unix or \s-1VMS\s0 environment.  If you
 233 encounter problems, or discover cases where the search could be improved,
 234 please let us know.
 235 .Sh "Win32 implementation"
 236 .IX Subsection "Win32 implementation"
 237 The version of \fIext()\fR which is executed under Win32 differs from the
 238 Unix\-OS/2 version in several respects:
 239 .IP "\(bu" 2
 240 If \f(CW$potential_libs\fR is empty, the return value will be empty.
 241 Otherwise, the libraries specified by \f(CW$Config{perllibs}\fR (see Config.pm)
 242 will be appended to the list of \f(CW$potential_libs\fR.  The libraries
 243 will be searched for in the directories specified in \f(CW$potential_libs\fR,
 244 \&\f(CW$Config{libpth}\fR, and in \f(CW\*(C`$Config{installarchlib}/CORE\*(C'\fR.
 245 For each library that is found,  a space-separated list of fully qualified
 246 library pathnames is generated.
 247 .IP "\(bu" 2
 248 Input library and path specifications are accepted with or without the
 249 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers.
 250 .Sp
 251 An entry of the form \f(CW\*(C`\-La:\efoo\*(C'\fR specifies the \f(CW\*(C`a:\efoo\*(C'\fR directory to look
 252 for the libraries that follow.
 253 .Sp
 254 An entry of the form \f(CW\*(C`\-lfoo\*(C'\fR specifies the library \f(CW\*(C`foo\*(C'\fR, which may be
 255 spelled differently depending on what kind of compiler you are using.  If
 256 you are using \s-1GCC\s0, it gets translated to \f(CW\*(C`libfoo.a\*(C'\fR, but for other win32
 257 compilers, it becomes \f(CW\*(C`foo.lib\*(C'\fR.  If no files are found by those translated
 258 names, one more attempt is made to find them using either \f(CW\*(C`foo.a\*(C'\fR or
 259 \&\f(CW\*(C`libfoo.lib\*(C'\fR, depending on whether \s-1GCC\s0 or some other win32 compiler is
 260 being used, respectively.
 261 .Sp
 262 If neither the \f(CW\*(C`\-L\*(C'\fR or \f(CW\*(C`\-l\*(C'\fR prefix is present in an entry, the entry is
 263 considered a directory to search if it is in fact a directory, and a
 264 library to search for otherwise.  The \f(CW$Config{lib_ext}\fR suffix will
 265 be appended to any entries that are not directories and don't already have
 266 the suffix.
 267 .Sp
 268 Note that the \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR prefixes are \fBnot required\fR, but authors
 269 who wish their extensions to be portable to Unix or \s-1OS/2\s0 should use the
 270 prefixes, since the Unix\-OS/2 version of \fIext()\fR requires them.
 271 .IP "\(bu" 2
 272 Entries cannot be plain object files, as many Win32 compilers will
 273 not handle object files in the place of libraries.
 274 .IP "\(bu" 2
 275 Entries in \f(CW$potential_libs\fR beginning with a colon and followed by
 276 alphanumeric characters are treated as flags.  Unknown flags will be ignored.
 277 .Sp
 278 An entry that matches \f(CW\*(C`/:nodefault/i\*(C'\fR disables the appending of default
 279 libraries found in \f(CW$Config{perllibs}\fR (this should be only needed very rarely).
 280 .Sp
 281 An entry that matches \f(CW\*(C`/:nosearch/i\*(C'\fR disables all searching for
 282 the libraries specified after it.  Translation of \f(CW\*(C`\-Lfoo\*(C'\fR and
 283 \&\f(CW\*(C`\-lfoo\*(C'\fR still happens as appropriate (depending on compiler being used,
 284 as reflected by \f(CW$Config{cc}\fR), but the entries are not verified to be
 285 valid files or directories.
 286 .Sp
 287 An entry that matches \f(CW\*(C`/:search/i\*(C'\fR reenables searching for
 288 the libraries specified after it.  You can put it at the end to
 289 enable searching for default libraries specified by \f(CW$Config{perllibs}\fR.
 290 .IP "\(bu" 2
 291 The libraries specified may be a mixture of static libraries and
 292 import libraries (to link with DLLs).  Since both kinds are used
 293 pretty transparently on the Win32 platform, we do not attempt to
 294 distinguish between them.
 295 .IP "\(bu" 2
 296 \&\s-1LDLOADLIBS\s0 and \s-1EXTRALIBS\s0 are always identical under Win32, and \s-1BSLOADLIBS\s0
 297 and \s-1LD_RUN_PATH\s0 are always empty (this may change in future).
 298 .IP "\(bu" 2
 299 You must make sure that any paths and path components are properly
 300 surrounded with double-quotes if they contain spaces. For example,
 301 \&\f(CW$potential_libs\fR could be (literally):
 302 .Sp
 303 .Vb 1
 304 \&        "\-Lc:\eProgram Files\evc\elib" msvcrt.lib "la test\efoo bar.lib"
 305 .Ve
 306 .Sp
 307 Note how the first and last entries are protected by quotes in order
 308 to protect the spaces.
 309 .IP "\(bu" 2
 310 Since this module is most often used only indirectly from extension
 311 \&\f(CW\*(C`Makefile.PL\*(C'\fR files, here is an example \f(CW\*(C`Makefile.PL\*(C'\fR entry to add
 312 a library to the build process for an extension:
 313 .Sp
 314 .Vb 1
 315 \&        LIBS => ['\-lgl']
 316 .Ve
 317 .Sp
 318 When using \s-1GCC\s0, that entry specifies that MakeMaker should first look
 319 for \f(CW\*(C`libgl.a\*(C'\fR (followed by \f(CW\*(C`gl.a\*(C'\fR) in all the locations specified by
 320 \&\f(CW$Config{libpth}\fR.
 321 .Sp
 322 When using a compiler other than \s-1GCC\s0, the above entry will search for
 323 \&\f(CW\*(C`gl.lib\*(C'\fR (followed by \f(CW\*(C`libgl.lib\*(C'\fR).
 324 .Sp
 325 If the library happens to be in a location not in \f(CW$Config{libpth}\fR,
 326 you need:
 327 .Sp
 328 .Vb 1
 329 \&        LIBS => ['\-Lc:\egllibs \-lgl']
 330 .Ve
 331 .Sp
 332 Here is a less often used example:
 333 .Sp
 334 .Vb 1
 335 \&        LIBS => ['\-lgl', ':nosearch \-Ld:\emesalibs \-lmesa \-luser32']
 336 .Ve
 337 .Sp
 338 This specifies a search for library \f(CW\*(C`gl\*(C'\fR as before.  If that search
 339 fails to find the library, it looks at the next item in the list. The
 340 \&\f(CW\*(C`:nosearch\*(C'\fR flag will prevent searching for the libraries that follow,
 341 so it simply returns the value as \f(CW\*(C`\-Ld:\emesalibs \-lmesa \-luser32\*(C'\fR,
 342 since \s-1GCC\s0 can use that value as is with its linker.
 343 .Sp
 344 When using the Visual C compiler, the second item is returned as
 345 \&\f(CW\*(C`\-libpath:d:\emesalibs mesa.lib user32.lib\*(C'\fR.
 346 .Sp
 347 When using the Borland compiler, the second item is returned as
 348 \&\f(CW\*(C`\-Ld:\emesalibs mesa.lib user32.lib\*(C'\fR, and MakeMaker takes care of
 349 moving the \f(CW\*(C`\-Ld:\emesalibs\*(C'\fR to the correct place in the linker
 350 command line.
 351 .SH "SEE ALSO"
 352 .IX Header "SEE ALSO"
 353 ExtUtils::MakeMaker