X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FExtUtils%3A%3ALiblist.3pm;fp=local-lib5%2Fman%2Fman3%2FExtUtils%3A%3ALiblist.3pm;h=ad5fbfab6621ca6676a02eb77cb90edc9c7d1fb9;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e diff --git a/local-lib5/man/man3/ExtUtils::Liblist.3pm b/local-lib5/man/man3/ExtUtils::Liblist.3pm new file mode 100644 index 0000000..ad5fbfa --- /dev/null +++ b/local-lib5/man/man3/ExtUtils::Liblist.3pm @@ -0,0 +1,353 @@ +.\" 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