--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "ExtUtils::Liblist 3"
+.TH ExtUtils::Liblist 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+ExtUtils::Liblist \- determine libraries to use and how to use them
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& require ExtUtils::Liblist;
+.Ve
+.PP
+.Vb 1
+\& $MM\->ext($potential_libs, $verbose, $need_names);
+.Ve
+.PP
+.Vb 2
+\& # Usually you can get away with:
+\& ExtUtils::Liblist\->ext($potential_libs, $verbose, $need_names)
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This utility takes a list of libraries in the form \f(CW\*(C`\-llib1 \-llib2
+\&\-llib3\*(C'\fR and returns lines suitable for inclusion in an extension
+Makefile. Extra library paths may be included with the form
+\&\f(CW\*(C`\-L/another/path\*(C'\fR this will affect the searches for all subsequent
+libraries.
+.PP
+It returns an array of four or five scalar values: \s-1EXTRALIBS\s0,
+\&\s-1BSLOADLIBS\s0, \s-1LDLOADLIBS\s0, \s-1LD_RUN_PATH\s0, and, optionally, a reference to
+the array of the filenames of actual libraries. Some of these don't
+mean anything unless on Unix. See the details about those platform
+specifics below. The list of the filenames is returned only if
+\&\f(CW$need_names\fR argument is true.
+.PP
+Dependent libraries can be linked in one of three ways:
+.IP "* For static extensions" 2
+.IX Item "For static extensions"
+by the ld command when the perl binary is linked with the extension
+library. See \s-1EXTRALIBS\s0 below.
+.IP "* For dynamic extensions at build/link time" 2
+.IX Item "For dynamic extensions at build/link time"
+by the ld command when the shared object is built/linked. See
+\&\s-1LDLOADLIBS\s0 below.
+.IP "* For dynamic extensions at load time" 2
+.IX Item "For dynamic extensions at load time"
+by the DynaLoader when the shared object is loaded. See \s-1BSLOADLIBS\s0
+below.
+.Sh "\s-1EXTRALIBS\s0"
+.IX Subsection "EXTRALIBS"
+List of libraries that need to be linked with when linking a perl
+binary which includes this extension. Only those libraries that
+actually exist are included. These are written to a file and used
+when linking perl.
+.Sh "\s-1LDLOADLIBS\s0 and \s-1LD_RUN_PATH\s0"
+.IX Subsection "LDLOADLIBS and LD_RUN_PATH"
+List of those libraries which can or must be linked into the shared
+library when created using ld. These may be static or dynamic
+libraries. \s-1LD_RUN_PATH\s0 is a colon separated list of the directories
+in \s-1LDLOADLIBS\s0. It is passed as an environment variable to the process
+that links the shared library.
+.Sh "\s-1BSLOADLIBS\s0"
+.IX Subsection "BSLOADLIBS"
+List of those libraries that are needed but can be linked in
+dynamically at run time on this platform. SunOS/Solaris does not need
+this because ld records the information (from \s-1LDLOADLIBS\s0) into the
+object file. This list is used to create a .bs (bootstrap) file.
+.SH "PORTABILITY"
+.IX Header "PORTABILITY"
+This module deals with a lot of system dependencies and has quite a
+few architecture specific \f(CW\*(C`if\*(C'\fRs in the code.
+.Sh "\s-1VMS\s0 implementation"
+.IX Subsection "VMS implementation"
+The version of \fIext()\fR which is executed under \s-1VMS\s0 differs from the
+Unix\-OS/2 version in several respects:
+.IP "\(bu" 2
+Input library and path specifications are accepted with or without the
+\&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers. If neither prefix is
+present, a token is considered a directory to search if it is in fact
+a directory, and a library to search for otherwise. Authors who wish
+their extensions to be portable to Unix or \s-1OS/2\s0 should use the Unix
+prefixes, since the Unix\-OS/2 version of \fIext()\fR requires them.
+.IP "\(bu" 2
+Wherever possible, shareable images are preferred to object libraries,
+and object libraries to plain object files. In accordance with \s-1VMS\s0
+naming conventions, \fIext()\fR looks for files named \fIlib\fRshr and \fIlib\fRrtl;
+it also looks for \fIlib\fRlib and lib\fIlib\fR to accommodate Unix conventions
+used in some ported software.
+.IP "\(bu" 2
+For each library that is found, an appropriate directive for a linker options
+file is generated. The return values are space-separated strings of
+these directives, rather than elements used on the linker command line.
+.IP "\(bu" 2
+\&\s-1LDLOADLIBS\s0 contains both the libraries found based on \f(CW$potential_libs\fR and
+the CRTLs, if any, specified in Config.pm. \s-1EXTRALIBS\s0 contains just those
+libraries found based on \f(CW$potential_libs\fR. \s-1BSLOADLIBS\s0 and \s-1LD_RUN_PATH\s0
+are always empty.
+.PP
+In addition, an attempt is made to recognize several common Unix library
+names, and filter them out or convert them to their \s-1VMS\s0 equivalents, as
+appropriate.
+.PP
+In general, the \s-1VMS\s0 version of \fIext()\fR should properly handle input from
+extensions originally designed for a Unix or \s-1VMS\s0 environment. If you
+encounter problems, or discover cases where the search could be improved,
+please let us know.
+.Sh "Win32 implementation"
+.IX Subsection "Win32 implementation"
+The version of \fIext()\fR which is executed under Win32 differs from the
+Unix\-OS/2 version in several respects:
+.IP "\(bu" 2
+If \f(CW$potential_libs\fR is empty, the return value will be empty.
+Otherwise, the libraries specified by \f(CW$Config{perllibs}\fR (see Config.pm)
+will be appended to the list of \f(CW$potential_libs\fR. The libraries
+will be searched for in the directories specified in \f(CW$potential_libs\fR,
+\&\f(CW$Config{libpth}\fR, and in \f(CW\*(C`$Config{installarchlib}/CORE\*(C'\fR.
+For each library that is found, a space-separated list of fully qualified
+library pathnames is generated.
+.IP "\(bu" 2
+Input library and path specifications are accepted with or without the
+\&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers.
+.Sp
+An entry of the form \f(CW\*(C`\-La:\efoo\*(C'\fR specifies the \f(CW\*(C`a:\efoo\*(C'\fR directory to look
+for the libraries that follow.
+.Sp
+An entry of the form \f(CW\*(C`\-lfoo\*(C'\fR specifies the library \f(CW\*(C`foo\*(C'\fR, which may be
+spelled differently depending on what kind of compiler you are using. If
+you are using \s-1GCC\s0, it gets translated to \f(CW\*(C`libfoo.a\*(C'\fR, but for other win32
+compilers, it becomes \f(CW\*(C`foo.lib\*(C'\fR. If no files are found by those translated
+names, one more attempt is made to find them using either \f(CW\*(C`foo.a\*(C'\fR or
+\&\f(CW\*(C`libfoo.lib\*(C'\fR, depending on whether \s-1GCC\s0 or some other win32 compiler is
+being used, respectively.
+.Sp
+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
+considered a directory to search if it is in fact a directory, and a
+library to search for otherwise. The \f(CW$Config{lib_ext}\fR suffix will
+be appended to any entries that are not directories and don't already have
+the suffix.
+.Sp
+Note that the \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR prefixes are \fBnot required\fR, but authors
+who wish their extensions to be portable to Unix or \s-1OS/2\s0 should use the
+prefixes, since the Unix\-OS/2 version of \fIext()\fR requires them.
+.IP "\(bu" 2
+Entries cannot be plain object files, as many Win32 compilers will
+not handle object files in the place of libraries.
+.IP "\(bu" 2
+Entries in \f(CW$potential_libs\fR beginning with a colon and followed by
+alphanumeric characters are treated as flags. Unknown flags will be ignored.
+.Sp
+An entry that matches \f(CW\*(C`/:nodefault/i\*(C'\fR disables the appending of default
+libraries found in \f(CW$Config{perllibs}\fR (this should be only needed very rarely).
+.Sp
+An entry that matches \f(CW\*(C`/:nosearch/i\*(C'\fR disables all searching for
+the libraries specified after it. Translation of \f(CW\*(C`\-Lfoo\*(C'\fR and
+\&\f(CW\*(C`\-lfoo\*(C'\fR still happens as appropriate (depending on compiler being used,
+as reflected by \f(CW$Config{cc}\fR), but the entries are not verified to be
+valid files or directories.
+.Sp
+An entry that matches \f(CW\*(C`/:search/i\*(C'\fR reenables searching for
+the libraries specified after it. You can put it at the end to
+enable searching for default libraries specified by \f(CW$Config{perllibs}\fR.
+.IP "\(bu" 2
+The libraries specified may be a mixture of static libraries and
+import libraries (to link with DLLs). Since both kinds are used
+pretty transparently on the Win32 platform, we do not attempt to
+distinguish between them.
+.IP "\(bu" 2
+\&\s-1LDLOADLIBS\s0 and \s-1EXTRALIBS\s0 are always identical under Win32, and \s-1BSLOADLIBS\s0
+and \s-1LD_RUN_PATH\s0 are always empty (this may change in future).
+.IP "\(bu" 2
+You must make sure that any paths and path components are properly
+surrounded with double-quotes if they contain spaces. For example,
+\&\f(CW$potential_libs\fR could be (literally):
+.Sp
+.Vb 1
+\& "\-Lc:\eProgram Files\evc\elib" msvcrt.lib "la test\efoo bar.lib"
+.Ve
+.Sp
+Note how the first and last entries are protected by quotes in order
+to protect the spaces.
+.IP "\(bu" 2
+Since this module is most often used only indirectly from extension
+\&\f(CW\*(C`Makefile.PL\*(C'\fR files, here is an example \f(CW\*(C`Makefile.PL\*(C'\fR entry to add
+a library to the build process for an extension:
+.Sp
+.Vb 1
+\& LIBS => ['\-lgl']
+.Ve
+.Sp
+When using \s-1GCC\s0, that entry specifies that MakeMaker should first look
+for \f(CW\*(C`libgl.a\*(C'\fR (followed by \f(CW\*(C`gl.a\*(C'\fR) in all the locations specified by
+\&\f(CW$Config{libpth}\fR.
+.Sp
+When using a compiler other than \s-1GCC\s0, the above entry will search for
+\&\f(CW\*(C`gl.lib\*(C'\fR (followed by \f(CW\*(C`libgl.lib\*(C'\fR).
+.Sp
+If the library happens to be in a location not in \f(CW$Config{libpth}\fR,
+you need:
+.Sp
+.Vb 1
+\& LIBS => ['\-Lc:\egllibs \-lgl']
+.Ve
+.Sp
+Here is a less often used example:
+.Sp
+.Vb 1
+\& LIBS => ['\-lgl', ':nosearch \-Ld:\emesalibs \-lmesa \-luser32']
+.Ve
+.Sp
+This specifies a search for library \f(CW\*(C`gl\*(C'\fR as before. If that search
+fails to find the library, it looks at the next item in the list. The
+\&\f(CW\*(C`:nosearch\*(C'\fR flag will prevent searching for the libraries that follow,
+so it simply returns the value as \f(CW\*(C`\-Ld:\emesalibs \-lmesa \-luser32\*(C'\fR,
+since \s-1GCC\s0 can use that value as is with its linker.
+.Sp
+When using the Visual C compiler, the second item is returned as
+\&\f(CW\*(C`\-libpath:d:\emesalibs mesa.lib user32.lib\*(C'\fR.
+.Sp
+When using the Borland compiler, the second item is returned as
+\&\f(CW\*(C`\-Ld:\emesalibs mesa.lib user32.lib\*(C'\fR, and MakeMaker takes care of
+moving the \f(CW\*(C`\-Ld:\emesalibs\*(C'\fR to the correct place in the linker
+command line.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+ExtUtils::MakeMaker
projects / catagits/Gitalist.git / blobdiff