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