Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::Liblist.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::Liblist 3pm"
61 .TH ExtUtils::Liblist 3pm 2026-05-26 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::Liblist \- determine libraries to use and how to use them
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& require ExtUtils::Liblist;
72 \&
73 \& $MM\->ext($potential_libs, $verbose, $need_names);
74 \&
75 \& # Usually you can get away with:
76 \& ExtUtils::Liblist\->ext($potential_libs, $verbose, $need_names)
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 This utility takes a list of libraries in the form \f(CW\*(C`\-llib1 \-llib2
81 \&\-llib3\*(C'\fR and returns lines suitable for inclusion in an extension
82 Makefile. Extra library paths may be included with the form
83 \&\f(CW\*(C`\-L/another/path\*(C'\fR this will affect the searches for all subsequent
84 libraries.
85 .PP
86 It returns an array of four or five scalar values: EXTRALIBS,
87 BSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to
88 the array of the filenames of actual libraries. Some of these don\*(Aqt
89 mean anything unless on Unix. See the details about those platform
90 specifics below. The list of the filenames is returned only if
91 \&\f(CW$need_names\fR argument is true.
92 .PP
93 Dependent libraries can be linked in one of three ways:
94 .IP \(bu 2
95 For static extensions
96 .Sp
97 by the ld command when the perl binary is linked with the extension
98 library. See EXTRALIBS below.
99 .IP \(bu 2
100 For dynamic extensions at build/link time
101 .Sp
102 by the ld command when the shared object is built/linked. See
103 LDLOADLIBS below.
104 .IP \(bu 2
105 For dynamic extensions at load time
106 .Sp
107 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
108 below.
109 .SS EXTRALIBS
110 .IX Subsection "EXTRALIBS"
111 List of libraries that need to be linked with when linking a perl
112 binary which includes this extension. Only those libraries that
113 actually exist are included. These are written to a file and used
114 when linking perl.
115 .SS "LDLOADLIBS and LD_RUN_PATH"
116 .IX Subsection "LDLOADLIBS and LD_RUN_PATH"
117 List of those libraries which can or must be linked into the shared
118 library when created using ld. These may be static or dynamic
119 libraries. LD_RUN_PATH is a colon separated list of the directories
120 in LDLOADLIBS. It is passed as an environment variable to the process
121 that links the shared library.
122 .PP
123 Fedora extension: This generation of LD_RUN_PATH is disabled by default.
124 To use the generated LD_RUN_PATH for all links, set the USE_MM_LD_RUN_PATH
125 MakeMaker object attribute / argument, (or set the \f(CW$USE_MM_LD_RUN_PATH\fR
126 environment variable).
127 .SS BSLOADLIBS
128 .IX Subsection "BSLOADLIBS"
129 List of those libraries that are needed but can be linked in
130 dynamically at run time on this platform. SunOS/Solaris does not need
131 this because ld records the information (from LDLOADLIBS) into the
132 object file. This list is used to create a .bs (bootstrap) file.
133 .SH PORTABILITY
134 .IX Header "PORTABILITY"
135 This module deals with a lot of system dependencies and has quite a
136 few architecture specific \f(CW\*(C`if\*(C'\fRs in the code.
137 .SS "VMS implementation"
138 .IX Subsection "VMS implementation"
139 The version of \fBext()\fR which is executed under VMS differs from the
140 Unix\-OS/2 version in several respects:
141 .IP \(bu 2
142 Input library and path specifications are accepted with or without the
143 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers. If neither prefix is
144 present, a token is considered a directory to search if it is in fact
145 a directory, and a library to search for otherwise. Authors who wish
146 their extensions to be portable to Unix or OS/2 should use the Unix
147 prefixes, since the Unix\-OS/2 version of \fBext()\fR requires them.
148 .IP \(bu 2
149 Wherever possible, shareable images are preferred to object libraries,
150 and object libraries to plain object files. In accordance with VMS
151 naming conventions, \fBext()\fR looks for files named \fIlib\fRshr and \fIlib\fRrtl;
152 it also looks for \fIlib\fRlib and lib\fIlib\fR to accommodate Unix conventions
153 used in some ported software.
154 .IP \(bu 2
155 For each library that is found, an appropriate directive for a linker options
156 file is generated. The return values are space\-separated strings of
157 these directives, rather than elements used on the linker command line.
158 .IP \(bu 2
159 LDLOADLIBS contains both the libraries found based on \f(CW$potential_libs\fR and
160 the CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those
161 libraries found based on \f(CW$potential_libs\fR. BSLOADLIBS and LD_RUN_PATH
162 are always empty.
163 .PP
164 In addition, an attempt is made to recognize several common Unix library
165 names, and filter them out or convert them to their VMS equivalents, as
166 appropriate.
167 .PP
168 In general, the VMS version of \fBext()\fR should properly handle input from
169 extensions originally designed for a Unix or VMS environment. If you
170 encounter problems, or discover cases where the search could be improved,
171 please let us know.
172 .SS "Win32 implementation"
173 .IX Subsection "Win32 implementation"
174 The version of \fBext()\fR which is executed under Win32 differs from the
175 Unix\-OS/2 version in several respects:
176 .IP \(bu 2
177 If \f(CW$potential_libs\fR is empty, the return value will be empty.
178 Otherwise, the libraries specified by \f(CW$Config{perllibs}\fR (see Config.pm)
179 will be appended to the list of \f(CW$potential_libs\fR. The libraries
180 will be searched for in the directories specified in \f(CW$potential_libs\fR,
181 \&\f(CW$Config{libpth}\fR, and in \f(CW\*(C`$Config{installarchlib}/CORE\*(C'\fR.
182 For each library that is found, a space\-separated list of fully qualified
183 library pathnames is generated.
184 .IP \(bu 2
185 Input library and path specifications are accepted with or without the
186 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers.
187 .Sp
188 An entry of the form \f(CW\*(C`\-La:\efoo\*(C'\fR specifies the \f(CW\*(C`a:\efoo\*(C'\fR directory to look
189 for the libraries that follow.
190 .Sp
191 An entry of the form \f(CW\*(C`\-lfoo\*(C'\fR specifies the library \f(CW\*(C`foo\*(C'\fR, which may be
192 spelled differently depending on what kind of compiler you are using. If
193 you are using GCC, it gets translated to \f(CW\*(C`libfoo.a\*(C'\fR, but for other win32
194 compilers, it becomes \f(CW\*(C`foo.lib\*(C'\fR. If no files are found by those translated
195 names, one more attempt is made to find them using either \f(CW\*(C`foo.a\*(C'\fR or
196 \&\f(CW\*(C`libfoo.lib\*(C'\fR, depending on whether GCC or some other win32 compiler is
197 being used, respectively.
198 .Sp
199 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
200 considered a directory to search if it is in fact a directory, and a
201 library to search for otherwise. The \f(CW$Config{lib_ext}\fR suffix will
202 be appended to any entries that are not directories and don\*(Aqt already have
203 the suffix.
204 .Sp
205 Note that the \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR prefixes are \fBnot required\fR, but authors
206 who wish their extensions to be portable to Unix or OS/2 should use the
207 prefixes, since the Unix\-OS/2 version of \fBext()\fR requires them.
208 .IP \(bu 2
209 Entries cannot be plain object files, as many Win32 compilers will
210 not handle object files in the place of libraries.
211 .IP \(bu 2
212 Entries in \f(CW$potential_libs\fR beginning with a colon and followed by
213 alphanumeric characters are treated as flags. Unknown flags will be ignored.
214 .Sp
215 An entry that matches \f(CW\*(C`/:nodefault/i\*(C'\fR disables the appending of default
216 libraries found in \f(CW$Config{perllibs}\fR (this should be only needed very rarely).
217 .Sp
218 An entry that matches \f(CW\*(C`/:nosearch/i\*(C'\fR disables all searching for
219 the libraries specified after it. Translation of \f(CW\*(C`\-Lfoo\*(C'\fR and
220 \&\f(CW\*(C`\-lfoo\*(C'\fR still happens as appropriate (depending on compiler being used,
221 as reflected by \f(CW$Config{cc}\fR), but the entries are not verified to be
222 valid files or directories.
223 .Sp
224 An entry that matches \f(CW\*(C`/:search/i\*(C'\fR reenables searching for
225 the libraries specified after it. You can put it at the end to
226 enable searching for default libraries specified by \f(CW$Config{perllibs}\fR.
227 .IP \(bu 2
228 The libraries specified may be a mixture of static libraries and
229 import libraries (to link with DLLs). Since both kinds are used
230 pretty transparently on the Win32 platform, we do not attempt to
231 distinguish between them.
232 .IP \(bu 2
233 LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
234 and LD_RUN_PATH are always empty (this may change in future).
235 .IP \(bu 2
236 You must make sure that any paths and path components are properly
237 surrounded with double\-quotes if they contain spaces. For example,
238 \&\f(CW$potential_libs\fR could be (literally):
239 .Sp
240 .Vb 1
241 \& "\-Lc:\eProgram Files\evc\elib" msvcrt.lib "la test\efoo bar.lib"
242 .Ve
243 .Sp
244 Note how the first and last entries are protected by quotes in order
245 to protect the spaces.
246 .IP \(bu 2
247 Since this module is most often used only indirectly from extension
248 \&\f(CW\*(C`Makefile.PL\*(C'\fR files, here is an example \f(CW\*(C`Makefile.PL\*(C'\fR entry to add
249 a library to the build process for an extension:
250 .Sp
251 .Vb 1
252 \& LIBS => [\*(Aq\-lgl\*(Aq]
253 .Ve
254 .Sp
255 When using GCC, that entry specifies that MakeMaker should first look
256 for \f(CW\*(C`libgl.a\*(C'\fR (followed by \f(CW\*(C`gl.a\*(C'\fR) in all the locations specified by
257 \&\f(CW$Config{libpth}\fR.
258 .Sp
259 When using a compiler other than GCC, the above entry will search for
260 \&\f(CW\*(C`gl.lib\*(C'\fR (followed by \f(CW\*(C`libgl.lib\*(C'\fR).
261 .Sp
262 If the library happens to be in a location not in \f(CW$Config{libpth}\fR,
263 you need:
264 .Sp
265 .Vb 1
266 \& LIBS => [\*(Aq\-Lc:\egllibs \-lgl\*(Aq]
267 .Ve
268 .Sp
269 Here is a less often used example:
270 .Sp
271 .Vb 1
272 \& LIBS => [\*(Aq\-lgl\*(Aq, \*(Aq:nosearch \-Ld:\emesalibs \-lmesa \-luser32\*(Aq]
273 .Ve
274 .Sp
275 This specifies a search for library \f(CW\*(C`gl\*(C'\fR as before. If that search
276 fails to find the library, it looks at the next item in the list. The
277 \&\f(CW\*(C`:nosearch\*(C'\fR flag will prevent searching for the libraries that follow,
278 so it simply returns the value as \f(CW\*(C`\-Ld:\emesalibs \-lmesa \-luser32\*(C'\fR,
279 since GCC can use that value as is with its linker.
280 .Sp
281 When using the Visual C compiler, the second item is returned as
282 \&\f(CW\*(C`\-libpath:d:\emesalibs mesa.lib user32.lib\*(C'\fR.
283 .Sp
284 When using the Borland compiler, the second item is returned as
285 \&\f(CW\*(C`\-Ld:\emesalibs mesa.lib user32.lib\*(C'\fR, and MakeMaker takes care of
286 moving the \f(CW\*(C`\-Ld:\emesalibs\*(C'\fR to the correct place in the linker
287 command line.
288 .SH "SEE ALSO"
289 .IX Header "SEE ALSO"
290 ExtUtils::MakeMaker