| 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 | |