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