Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Liblist.3perl

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