This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to ExtUtils-MakeMaker-6.48
[perl5.git] / lib / ExtUtils / Liblist.pm
CommitLineData
005c1a0e 1package ExtUtils::Liblist;
17f410f9 2
1e65eb70
SP
3use strict;
4
b5b9b385 5our $VERSION = '6.48';
d0843067 6
f6d6199c
MS
7use File::Spec;
8require ExtUtils::Liblist::Kid;
a592ba15 9our @ISA = qw(ExtUtils::Liblist::Kid File::Spec);
e97e32e6 10
479d2113
MS
11# Backwards compatibility with old interface.
12sub ext {
13 goto &ExtUtils::Liblist::Kid::ext;
14}
15
e97e32e6
IZ
16sub lsdir {
17 shift;
18 my $rex = qr/$_[1]/;
57b1a898 19 opendir DIR, $_[0];
479d2113 20 my @out = grep /$rex/, readdir DIR;
57b1a898 21 closedir DIR;
479d2113 22 return @out;
e97e32e6
IZ
23}
24
864a5fa8 25__END__
cb1a09d0 26
864a5fa8
AD
27=head1 NAME
28
29ExtUtils::Liblist - determine libraries to use and how to use them
30
31=head1 SYNOPSIS
32
479d2113
MS
33 require ExtUtils::Liblist;
34
35 $MM->ext($potential_libs, $verbose, $need_names);
864a5fa8 36
479d2113
MS
37 # Usually you can get away with:
38 ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)
864a5fa8
AD
39
40=head1 DESCRIPTION
41
42This utility takes a list of libraries in the form C<-llib1 -llib2
76c6a468 43-llib3> and returns lines suitable for inclusion in an extension
864a5fa8
AD
44Makefile. Extra library paths may be included with the form
45C<-L/another/path> this will affect the searches for all subsequent
46libraries.
47
76c6a468
IZ
48It returns an array of four or five scalar values: EXTRALIBS,
49BSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to
50the array of the filenames of actual libraries. Some of these don't
51mean anything unless on Unix. See the details about those platform
52specifics below. The list of the filenames is returned only if
53$need_names argument is true.
864a5fa8
AD
54
55Dependent libraries can be linked in one of three ways:
56
57=over 2
58
59=item * For static extensions
60
61by the ld command when the perl binary is linked with the extension
62library. See EXTRALIBS below.
63
f6d6199c 64=item * For dynamic extensions at build/link time
864a5fa8
AD
65
66by the ld command when the shared object is built/linked. See
67LDLOADLIBS below.
68
f6d6199c 69=item * For dynamic extensions at load time
864a5fa8
AD
70
71by the DynaLoader when the shared object is loaded. See BSLOADLIBS
72below.
73
74=back
75
76=head2 EXTRALIBS
77
78List of libraries that need to be linked with when linking a perl
a7665c5e 79binary which includes this extension. Only those libraries that
864a5fa8
AD
80actually exist are included. These are written to a file and used
81when linking perl.
82
83=head2 LDLOADLIBS and LD_RUN_PATH
84
85List of those libraries which can or must be linked into the shared
86library when created using ld. These may be static or dynamic
87libraries. LD_RUN_PATH is a colon separated list of the directories
88in LDLOADLIBS. It is passed as an environment variable to the process
89that links the shared library.
90
91=head2 BSLOADLIBS
92
93List of those libraries that are needed but can be linked in
94dynamically at run time on this platform. SunOS/Solaris does not need
95this because ld records the information (from LDLOADLIBS) into the
96object file. This list is used to create a .bs (bootstrap) file.
97
98=head1 PORTABILITY
99
100This module deals with a lot of system dependencies and has quite a
a7665c5e 101few architecture specific C<if>s in the code.
864a5fa8 102
55497cff
PP
103=head2 VMS implementation
104
105The version of ext() which is executed under VMS differs from the
106Unix-OS/2 version in several respects:
107
108=over 2
109
110=item *
111
112Input library and path specifications are accepted with or without the
de592821 113C<-l> and C<-L> prefixes used by Unix linkers. If neither prefix is
55497cff
PP
114present, a token is considered a directory to search if it is in fact
115a directory, and a library to search for otherwise. Authors who wish
116their extensions to be portable to Unix or OS/2 should use the Unix
117prefixes, since the Unix-OS/2 version of ext() requires them.
118
119=item *
120
121Wherever possible, shareable images are preferred to object libraries,
122and object libraries to plain object files. In accordance with VMS
123naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
de592821 124it also looks for I<lib>lib and libI<lib> to accommodate Unix conventions
55497cff
PP
125used in some ported software.
126
127=item *
128
129For each library that is found, an appropriate directive for a linker options
130file is generated. The return values are space-separated strings of
131these directives, rather than elements used on the linker command line.
132
133=item *
134
09b7f37c
CB
135LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
136the CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those
137libraries found based on C<$potential_libs>. BSLOADLIBS and LD_RUN_PATH
138are always empty.
55497cff
PP
139
140=back
141
142In addition, an attempt is made to recognize several common Unix library
143names, and filter them out or convert them to their VMS equivalents, as
144appropriate.
145
146In general, the VMS version of ext() should properly handle input from
147extensions originally designed for a Unix or VMS environment. If you
148encounter problems, or discover cases where the search could be improved,
149please let us know.
150
3e3baf6d
TB
151=head2 Win32 implementation
152
153The version of ext() which is executed under Win32 differs from the
154Unix-OS/2 version in several respects:
155
156=over 2
157
158=item *
159
944acd49 160If C<$potential_libs> is empty, the return value will be empty.
9c839522 161Otherwise, the libraries specified by C<$Config{perllibs}> (see Config.pm)
944acd49 162will be appended to the list of C<$potential_libs>. The libraries
b11c3c9f
GS
163will be searched for in the directories specified in C<$potential_libs>,
164C<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
165For each library that is found, a space-separated list of fully qualified
166library pathnames is generated.
944acd49
GS
167
168=item *
169
3e3baf6d 170Input library and path specifications are accepted with or without the
de592821 171C<-l> and C<-L> prefixes used by Unix linkers.
944acd49
GS
172
173An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
174for the libraries that follow.
175
176An entry of the form C<-lfoo> specifies the library C<foo>, which may be
177spelled differently depending on what kind of compiler you are using. If
178you are using GCC, it gets translated to C<libfoo.a>, but for other win32
179compilers, it becomes C<foo.lib>. If no files are found by those translated
180names, one more attempt is made to find them using either C<foo.a> or
181C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
182being used, respectively.
183
184If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
185considered a directory to search if it is in fact a directory, and a
186library to search for otherwise. The C<$Config{lib_ext}> suffix will
187be appended to any entries that are not directories and don't already have
188the suffix.
189
de592821 190Note that the C<-L> and C<-l> prefixes are B<not required>, but authors
944acd49
GS
191who wish their extensions to be portable to Unix or OS/2 should use the
192prefixes, since the Unix-OS/2 version of ext() requires them.
3e3baf6d
TB
193
194=item *
195
196Entries cannot be plain object files, as many Win32 compilers will
197not handle object files in the place of libraries.
198
199=item *
200
944acd49
GS
201Entries in C<$potential_libs> beginning with a colon and followed by
202alphanumeric characters are treated as flags. Unknown flags will be ignored.
203
204An entry that matches C</:nodefault/i> disables the appending of default
9c839522 205libraries found in C<$Config{perllibs}> (this should be only needed very rarely).
944acd49
GS
206
207An entry that matches C</:nosearch/i> disables all searching for
208the libraries specified after it. Translation of C<-Lfoo> and
209C<-lfoo> still happens as appropriate (depending on compiler being used,
210as reflected by C<$Config{cc}>), but the entries are not verified to be
211valid files or directories.
3e3baf6d 212
e47a9bbc
GS
213An entry that matches C</:search/i> reenables searching for
214the libraries specified after it. You can put it at the end to
9c839522 215enable searching for default libraries specified by C<$Config{perllibs}>.
e47a9bbc 216
3e3baf6d
TB
217=item *
218
219The libraries specified may be a mixture of static libraries and
220import libraries (to link with DLLs). Since both kinds are used
a7665c5e 221pretty transparently on the Win32 platform, we do not attempt to
3e3baf6d
TB
222distinguish between them.
223
224=item *
225
226LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
227and LD_RUN_PATH are always empty (this may change in future).
228
ecc90c0e
GS
229=item *
230
231You must make sure that any paths and path components are properly
232surrounded with double-quotes if they contain spaces. For example,
233C<$potential_libs> could be (literally):
234
235 "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
236
237Note how the first and last entries are protected by quotes in order
238to protect the spaces.
239
944acd49
GS
240=item *
241
242Since this module is most often used only indirectly from extension
243C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
e47a9bbc 244a library to the build process for an extension:
944acd49
GS
245
246 LIBS => ['-lgl']
247
248When using GCC, that entry specifies that MakeMaker should first look
249for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
250C<$Config{libpth}>.
251
252When using a compiler other than GCC, the above entry will search for
253C<gl.lib> (followed by C<libgl.lib>).
254
e47a9bbc
GS
255If the library happens to be in a location not in C<$Config{libpth}>,
256you need:
257
258 LIBS => ['-Lc:\gllibs -lgl']
259
944acd49
GS
260Here is a less often used example:
261
262 LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
263
264This specifies a search for library C<gl> as before. If that search
265fails to find the library, it looks at the next item in the list. The
266C<:nosearch> flag will prevent searching for the libraries that follow,
267so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
268since GCC can use that value as is with its linker.
269
270When using the Visual C compiler, the second item is returned as
271C<-libpath:d:\mesalibs mesa.lib user32.lib>.
272
273When using the Borland compiler, the second item is returned as
e47a9bbc
GS
274C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
275moving the C<-Ld:\mesalibs> to the correct place in the linker
276command line.
944acd49 277
3e3baf6d
TB
278=back
279
280
864a5fa8
AD
281=head1 SEE ALSO
282
283L<ExtUtils::MakeMaker>
284
285=cut
286