File Coverage

lib/ExtUtils/Liblist.pm
Criterion Covered Total %
statement 16 16 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod 0 2 0.0
total 21 23 91.3


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