Debian Codegraph @

upstream/opensuse-tumbleweed/man3/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-03-09 "perl v5.42.1" "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 .SS BSLOADLIBS
123 .IX Subsection "BSLOADLIBS"
124 List of those libraries that are needed but can be linked in
125 dynamically at run time on this platform. SunOS/Solaris does not need
126 this because ld records the information (from LDLOADLIBS) into the
127 object file. This list is used to create a .bs (bootstrap) file.
128 .SH PORTABILITY
129 .IX Header "PORTABILITY"
130 This module deals with a lot of system dependencies and has quite a
131 few architecture specific \f(CW\*(C`if\*(C'\fRs in the code.
132 .SS "VMS implementation"
133 .IX Subsection "VMS implementation"
134 The version of \fBext()\fR which is executed under VMS differs from the
135 Unix\-OS/2 version in several respects:
136 .IP \(bu 2
137 Input library and path specifications are accepted with or without the
138 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers. If neither prefix is
139 present, a token is considered a directory to search if it is in fact
140 a directory, and a library to search for otherwise. Authors who wish
141 their extensions to be portable to Unix or OS/2 should use the Unix
142 prefixes, since the Unix\-OS/2 version of \fBext()\fR requires them.
143 .IP \(bu 2
144 Wherever possible, shareable images are preferred to object libraries,
145 and object libraries to plain object files. In accordance with VMS
146 naming conventions, \fBext()\fR looks for files named \fIlib\fRshr and \fIlib\fRrtl;
147 it also looks for \fIlib\fRlib and lib\fIlib\fR to accommodate Unix conventions
148 used in some ported software.
149 .IP \(bu 2
150 For each library that is found, an appropriate directive for a linker options
151 file is generated. The return values are space\-separated strings of
152 these directives, rather than elements used on the linker command line.
153 .IP \(bu 2
154 LDLOADLIBS contains both the libraries found based on \f(CW$potential_libs\fR and
155 the CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those
156 libraries found based on \f(CW$potential_libs\fR. BSLOADLIBS and LD_RUN_PATH
157 are always empty.
158 .PP
159 In addition, an attempt is made to recognize several common Unix library
160 names, and filter them out or convert them to their VMS equivalents, as
161 appropriate.
162 .PP
163 In general, the VMS version of \fBext()\fR should properly handle input from
164 extensions originally designed for a Unix or VMS environment. If you
165 encounter problems, or discover cases where the search could be improved,
166 please let us know.
167 .SS "Win32 implementation"
168 .IX Subsection "Win32 implementation"
169 The version of \fBext()\fR which is executed under Win32 differs from the
170 Unix\-OS/2 version in several respects:
171 .IP \(bu 2
172 If \f(CW$potential_libs\fR is empty, the return value will be empty.
173 Otherwise, the libraries specified by \f(CW$Config{perllibs}\fR (see Config.pm)
174 will be appended to the list of \f(CW$potential_libs\fR. The libraries
175 will be searched for in the directories specified in \f(CW$potential_libs\fR,
176 \&\f(CW$Config{libpth}\fR, and in \f(CW\*(C`$Config{installarchlib}/CORE\*(C'\fR.
177 For each library that is found, a space\-separated list of fully qualified
178 library pathnames is generated.
179 .IP \(bu 2
180 Input library and path specifications are accepted with or without the
181 \&\f(CW\*(C`\-l\*(C'\fR and \f(CW\*(C`\-L\*(C'\fR prefixes used by Unix linkers.
182 .Sp
183 An entry of the form \f(CW\*(C`\-La:\efoo\*(C'\fR specifies the \f(CW\*(C`a:\efoo\*(C'\fR directory to look
184 for the libraries that follow.
185 .Sp
186 An entry of the form \f(CW\*(C`\-lfoo\*(C'\fR specifies the library \f(CW\*(C`foo\*(C'\fR, which may be
187 spelled differently depending on what kind of compiler you are using. If
188 you are using GCC, it gets translated to \f(CW\*(C`libfoo.a\*(C'\fR, but for other win32
189 compilers, it becomes \f(CW\*(C`foo.lib\*(C'\fR. If no files are found by those translated
190 names, one more attempt is made to find them using either \f(CW\*(C`foo.a\*(C'\fR or
191 \&\f(CW\*(C`libfoo.lib\*(C'\fR, depending on whether GCC or some other win32 compiler is
192 being used, respectively.
193 .Sp
194 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
195 considered a directory to search if it is in fact a directory, and a
196 library to search for otherwise. The \f(CW$Config{lib_ext}\fR suffix will
197 be appended to any entries that are not directories and don\*(Aqt already have
198 the suffix.
199 .Sp
200 Note that the \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR prefixes are \fBnot required\fR, but authors
201 who wish their extensions to be portable to Unix or OS/2 should use the
202 prefixes, since the Unix\-OS/2 version of \fBext()\fR requires them.
203 .IP \(bu 2
204 Entries cannot be plain object files, as many Win32 compilers will
205 not handle object files in the place of libraries.
206 .IP \(bu 2
207 Entries in \f(CW$potential_libs\fR beginning with a colon and followed by
208 alphanumeric characters are treated as flags. Unknown flags will be ignored.
209 .Sp
210 An entry that matches \f(CW\*(C`/:nodefault/i\*(C'\fR disables the appending of default
211 libraries found in \f(CW$Config{perllibs}\fR (this should be only needed very rarely).
212 .Sp
213 An entry that matches \f(CW\*(C`/:nosearch/i\*(C'\fR disables all searching for
214 the libraries specified after it. Translation of \f(CW\*(C`\-Lfoo\*(C'\fR and
215 \&\f(CW\*(C`\-lfoo\*(C'\fR still happens as appropriate (depending on compiler being used,
216 as reflected by \f(CW$Config{cc}\fR), but the entries are not verified to be
217 valid files or directories.
218 .Sp
219 An entry that matches \f(CW\*(C`/:search/i\*(C'\fR reenables searching for
220 the libraries specified after it. You can put it at the end to
221 enable searching for default libraries specified by \f(CW$Config{perllibs}\fR.
222 .IP \(bu 2
223 The libraries specified may be a mixture of static libraries and
224 import libraries (to link with DLLs). Since both kinds are used
225 pretty transparently on the Win32 platform, we do not attempt to
226 distinguish between them.
227 .IP \(bu 2
228 LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
229 and LD_RUN_PATH are always empty (this may change in future).
230 .IP \(bu 2
231 You must make sure that any paths and path components are properly
232 surrounded with double\-quotes if they contain spaces. For example,
233 \&\f(CW$potential_libs\fR could be (literally):
234 .Sp
235 .Vb 1
236 \& "\-Lc:\eProgram Files\evc\elib" msvcrt.lib "la test\efoo bar.lib"
237 .Ve
238 .Sp
239 Note how the first and last entries are protected by quotes in order
240 to protect the spaces.
241 .IP \(bu 2
242 Since this module is most often used only indirectly from extension
243 \&\f(CW\*(C`Makefile.PL\*(C'\fR files, here is an example \f(CW\*(C`Makefile.PL\*(C'\fR entry to add
244 a library to the build process for an extension:
245 .Sp
246 .Vb 1
247 \& LIBS => [\*(Aq\-lgl\*(Aq]
248 .Ve
249 .Sp
250 When using GCC, that entry specifies that MakeMaker should first look
251 for \f(CW\*(C`libgl.a\*(C'\fR (followed by \f(CW\*(C`gl.a\*(C'\fR) in all the locations specified by
252 \&\f(CW$Config{libpth}\fR.
253 .Sp
254 When using a compiler other than GCC, the above entry will search for
255 \&\f(CW\*(C`gl.lib\*(C'\fR (followed by \f(CW\*(C`libgl.lib\*(C'\fR).
256 .Sp
257 If the library happens to be in a location not in \f(CW$Config{libpth}\fR,
258 you need:
259 .Sp
260 .Vb 1
261 \& LIBS => [\*(Aq\-Lc:\egllibs \-lgl\*(Aq]
262 .Ve
263 .Sp
264 Here is a less often used example:
265 .Sp
266 .Vb 1
267 \& LIBS => [\*(Aq\-lgl\*(Aq, \*(Aq:nosearch \-Ld:\emesalibs \-lmesa \-luser32\*(Aq]
268 .Ve
269 .Sp
270 This specifies a search for library \f(CW\*(C`gl\*(C'\fR as before. If that search
271 fails to find the library, it looks at the next item in the list. The
272 \&\f(CW\*(C`:nosearch\*(C'\fR flag will prevent searching for the libraries that follow,
273 so it simply returns the value as \f(CW\*(C`\-Ld:\emesalibs \-lmesa \-luser32\*(C'\fR,
274 since GCC can use that value as is with its linker.
275 .Sp
276 When using the Visual C compiler, the second item is returned as
277 \&\f(CW\*(C`\-libpath:d:\emesalibs mesa.lib user32.lib\*(C'\fR.
278 .Sp
279 When using the Borland compiler, the second item is returned as
280 \&\f(CW\*(C`\-Ld:\emesalibs mesa.lib user32.lib\*(C'\fR, and MakeMaker takes care of
281 moving the \f(CW\*(C`\-Ld:\emesalibs\*(C'\fR to the correct place in the linker
282 command line.
283 .SH "SEE ALSO"
284 .IX Header "SEE ALSO"
285 ExtUtils::MakeMaker