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