1ExtUtils::Liblist(3pm) Perl Programmers Reference Guide ExtUtils::Liblist(3pm)
2
6 ExtUtils::Liblist - determine libraries to use and how to use them
7
9 require ExtUtils::Liblist;
10 $MM->ext($potential_libs, $verbose, $need_names);
12 # Usually you can get away with:
14 ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)
15
17 This utility takes a list of libraries in the form "-llib1 -llib2
18 -llib3" and returns lines suitable for inclusion in an extension Make‐
19 file. Extra library paths may be included with the form
20 "-L/another/path" this will affect the searches for all subsequent
21 libraries.
22 It returns an array of four or five scalar values: EXTRALIBS, BSLOAD‐
24 LIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to the
25 array of the filenames of actual libraries. Some of these don't mean
26 anything unless on Unix. See the details about those platform
27 specifics below. The list of the filenames is returned only if
28 $need_names argument is true.
29 Dependent libraries can be linked in one of three ways:
31 * For static extensions
33 by the ld command when the perl binary is linked with the extension
34 library. See EXTRALIBS below.
35 * For dynamic extensions at build/link time
37 by the ld command when the shared object is built/linked. See LDLOAD‐
38 LIBS below.
39 * For dynamic extensions at load time
41 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
42 below.
43 EXTRALIBS
45 List of libraries that need to be linked with when linking a perl
47 binary which includes this extension. Only those libraries that actu‐
48 ally exist are included. These are written to a file and used when
49 linking perl.
50 LDLOADLIBS and LD_RUN_PATH
52 List of those libraries which can or must be linked into the shared
54 library when created using ld. These may be static or dynamic
55 libraries. LD_RUN_PATH is a colon separated list of the directories in
56 LDLOADLIBS. It is passed as an environment variable to the process that
57 links the shared library.
58 Red Hat extension: This generation of LD_RUN_PATH is disabled by
60 default. To use the generated LD_RUN_PATH for all links, set the
61 USE_MM_LD_RUN_PATH MakeMaker object attribute / argument, (or set the
62 $USE_MM_LD_RUN_PATH environment variable).
63 BSLOADLIBS
65 List of those libraries that are needed but can be linked in dynami‐
67 cally at run time on this platform. SunOS/Solaris does not need this
68 because ld records the information (from LDLOADLIBS) into the object
69 file. This list is used to create a .bs (bootstrap) file.
70
72 This module deals with a lot of system dependencies and has quite a few
73 architecture specific "if"s in the code.
74 VMS implementation
76 The version of ext() which is executed under VMS differs from the
78 Unix-OS/2 version in several respects:
79 · Input library and path specifications are accepted with or without
81 the "-l" and "-L" prefixes used by Unix linkers. If neither prefix
82 is present, a token is considered a directory to search if it is in
83 fact a directory, and a library to search for otherwise. Authors who
84 wish their extensions to be portable to Unix or OS/2 should use the
85 Unix prefixes, since the Unix-OS/2 version of ext() requires them.
86 · Wherever possible, shareable images are preferred to object
88 libraries, and object libraries to plain object files. In accordance
89 with VMS naming conventions, ext() looks for files named libshr and
90 librtl; it also looks for liblib and liblib to accommodate Unix con‐
91 ventions used in some ported software.
92 · For each library that is found, an appropriate directive for a linker
94 options file is generated. The return values are space-separated
95 strings of these directives, rather than elements used on the linker
96 command line.
97 · LDLOADLIBS contains both the libraries found based on $potential_libs
99 and the CRTLs, if any, specified in Config.pm. EXTRALIBS contains
100 just those libraries found based on $potential_libs. BSLOADLIBS and
101 LD_RUN_PATH are always empty.
102 In addition, an attempt is made to recognize several common Unix
104 library names, and filter them out or convert them to their VMS equiva‐
105 lents, as appropriate.
106 In general, the VMS version of ext() should properly handle input from
108 extensions originally designed for a Unix or VMS environment. If you
109 encounter problems, or discover cases where the search could be
110 improved, please let us know.
111 Win32 implementation
113 The version of ext() which is executed under Win32 differs from the
115 Unix-OS/2 version in several respects:
116 · If $potential_libs is empty, the return value will be empty. Other‐
118 wise, the libraries specified by $Config{perllibs} (see Config.pm)
119 will be appended to the list of $potential_libs. The libraries will
120 be searched for in the directories specified in $potential_libs,
121 $Config{libpth}, and in "$Config{installarchlib}/CORE". For each
122 library that is found, a space-separated list of fully qualified
123 library pathnames is generated.
124 · Input library and path specifications are accepted with or without
126 the "-l" and "-L" prefixes used by Unix linkers.
127 An entry of the form "-La:\foo" specifies the "a:\foo" directory to
129 look for the libraries that follow.
130 An entry of the form "-lfoo" specifies the library "foo", which may
132 be spelled differently depending on what kind of compiler you are
133 using. If you are using GCC, it gets translated to "libfoo.a", but
134 for other win32 compilers, it becomes "foo.lib". If no files are
135 found by those translated names, one more attempt is made to find
136 them using either "foo.a" or "libfoo.lib", depending on whether GCC
137 or some other win32 compiler is being used, respectively.
138 If neither the "-L" or "-l" prefix is present in an entry, the entry
140 is considered a directory to search if it is in fact a directory, and
141 a library to search for otherwise. The $Config{lib_ext} suffix will
142 be appended to any entries that are not directories and don't already
143 have the suffix.
144 Note that the "-L" and "-l" prefixes are not required, but authors
146 who wish their extensions to be portable to Unix or OS/2 should use
147 the prefixes, since the Unix-OS/2 version of ext() requires them.
148 · Entries cannot be plain object files, as many Win32 compilers will
150 not handle object files in the place of libraries.
151 · Entries in $potential_libs beginning with a colon and followed by
153 alphanumeric characters are treated as flags. Unknown flags will be
154 ignored.
155 An entry that matches "/:nodefault/i" disables the appending of
157 default libraries found in $Config{perllibs} (this should be only
158 needed very rarely).
159 An entry that matches "/:nosearch/i" disables all searching for the
161 libraries specified after it. Translation of "-Lfoo" and "-lfoo"
162 still happens as appropriate (depending on compiler being used, as
163 reflected by $Config{cc}), but the entries are not verified to be
164 valid files or directories.
165 An entry that matches "/:search/i" reenables searching for the
167 libraries specified after it. You can put it at the end to enable
168 searching for default libraries specified by $Config{perllibs}.
169 · The libraries specified may be a mixture of static libraries and
171 import libraries (to link with DLLs). Since both kinds are used
172 pretty transparently on the Win32 platform, we do not attempt to dis‐
173 tinguish between them.
174 · LDLOADLIBS and EXTRALIBS are always identical under Win32, and
176 BSLOADLIBS and LD_RUN_PATH are always empty (this may change in
177 future).
178 · You must make sure that any paths and path components are properly
180 surrounded with double-quotes if they contain spaces. For example,
181 $potential_libs could be (literally):
182 "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
184 Note how the first and last entries are protected by quotes in order
186 to protect the spaces.
187 · Since this module is most often used only indirectly from extension
189 "Makefile.PL" files, here is an example "Makefile.PL" entry to add a
190 library to the build process for an extension:
191 LIBS => ['-lgl']
193 When using GCC, that entry specifies that MakeMaker should first look
195 for "libgl.a" (followed by "gl.a") in all the locations specified by
196 $Config{libpth}.
197 When using a compiler other than GCC, the above entry will search for
199 "gl.lib" (followed by "libgl.lib").
200 If the library happens to be in a location not in $Config{libpth},
202 you need:
203 LIBS => ['-Lc:\gllibs -lgl']
205 Here is a less often used example:
207 LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
209 This specifies a search for library "gl" as before. If that search
211 fails to find the library, it looks at the next item in the list. The
212 ":nosearch" flag will prevent searching for the libraries that fol‐
213 low, so it simply returns the value as "-Ld:\mesalibs -lmesa
214 -luser32", since GCC can use that value as is with its linker.
215 When using the Visual C compiler, the second item is returned as
217 "-libpath:d:\mesalibs mesa.lib user32.lib".
218 When using the Borland compiler, the second item is returned as
220 "-Ld:\mesalibs mesa.lib user32.lib", and MakeMaker takes care of mov‐
221 ing the "-Ld:\mesalibs" to the correct place in the linker command
222 line.
223
225 ExtUtils::MakeMaker
226perl v5.8.8 2001-09-21 ExtUtils::Liblist(3pm)