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