This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Liblist tweak suggested by Swen Thuemmler <Swen.Thuemmler@paderlinx.de>;
[perl5.git] / lib / ExtUtils / Liblist.pm
1 package ExtUtils::Liblist;
2 use vars qw($VERSION);
3 # Broken out of MakeMaker from version 4.11
4
5 $VERSION = substr q$Revision: 1.25 $, 10;
6
7 use Config;
8 use Cwd 'cwd';
9 use File::Basename;
10
11 sub ext {
12   if   ($^O eq 'VMS')     { return &_vms_ext;      }
13   elsif($^O eq 'MSWin32') { return &_win32_ext;    }
14   else                    { return &_unix_os2_ext; }
15 }
16
17 sub _unix_os2_ext {
18     my($self,$potential_libs, $verbose) = @_;
19     if ($^O =~ 'os2' and $Config{libs}) { 
20         # Dynamic libraries are not transitive, so we may need including
21         # the libraries linked against perl.dll again.
22
23         $potential_libs .= " " if $potential_libs;
24         $potential_libs .= $Config{libs};
25     }
26     return ("", "", "", "") unless $potential_libs;
27     warn "Potential libraries are '$potential_libs':\n" if $verbose;
28
29     my($so)   = $Config{'so'};
30     my($libs) = $Config{'libs'};
31     my $Config_libext = $Config{lib_ext} || ".a";
32
33
34     # compute $extralibs, $bsloadlibs and $ldloadlibs from
35     # $potential_libs
36     # this is a rewrite of Andy Dougherty's extliblist in perl
37
38     my(@searchpath); # from "-L/path" entries in $potential_libs
39     my(@libpath) = split " ", $Config{'libpth'};
40     my(@ldloadlibs, @bsloadlibs, @extralibs, @ld_run_path, %ld_run_path_seen);
41     my($fullname, $thislib, $thispth, @fullname);
42     my($pwd) = cwd(); # from Cwd.pm
43     my($found) = 0;
44
45     foreach $thislib (split ' ', $potential_libs){
46
47         # Handle possible linker path arguments.
48         if ($thislib =~ s/^(-[LR])//){  # save path flag type
49             my($ptype) = $1;
50             unless (-d $thislib){
51                 warn "$ptype$thislib ignored, directory does not exist\n"
52                         if $verbose;
53                 next;
54             }
55             unless ($self->file_name_is_absolute($thislib)) {
56               warn "Warning: $ptype$thislib changed to $ptype$pwd/$thislib\n";
57               $thislib = $self->catdir($pwd,$thislib);
58             }
59             push(@searchpath, $thislib);
60             push(@extralibs,  "$ptype$thislib");
61             push(@ldloadlibs, "$ptype$thislib");
62             next;
63         }
64
65         # Handle possible library arguments.
66         unless ($thislib =~ s/^-l//){
67           warn "Unrecognized argument in LIBS ignored: '$thislib'\n";
68           next;
69         }
70
71         my($found_lib)=0;
72         foreach $thispth (@searchpath, @libpath){
73
74                 # Try to find the full name of the library.  We need this to
75                 # determine whether it's a dynamically-loadable library or not.
76                 # This tends to be subject to various os-specific quirks.
77                 # For gcc-2.6.2 on linux (March 1995), DLD can not load
78                 # .sa libraries, with the exception of libm.sa, so we
79                 # deliberately skip them.
80             if (@fullname =
81                     $self->lsdir($thispth,"^\Qlib$thislib.$so.\E[0-9]+")){
82                 # Take care that libfoo.so.10 wins against libfoo.so.9.
83                 # Compare two libraries to find the most recent version
84                 # number.  E.g.  if you have libfoo.so.9.0.7 and
85                 # libfoo.so.10.1, first convert all digits into two
86                 # decimal places.  Then we'll add ".00" to the shorter
87                 # strings so that we're comparing strings of equal length
88                 # Thus we'll compare libfoo.so.09.07.00 with
89                 # libfoo.so.10.01.00.  Some libraries might have letters
90                 # in the version.  We don't know what they mean, but will
91                 # try to skip them gracefully -- we'll set any letter to
92                 # '0'.  Finally, sort in reverse so we can take the
93                 # first element.
94
95                 #TODO: iterate through the directory instead of sorting
96
97                 $fullname = "$thispth/" .
98                 (sort { my($ma) = $a;
99                         my($mb) = $b;
100                         $ma =~ tr/A-Za-z/0/s;
101                         $ma =~ s/\b(\d)\b/0$1/g;
102                         $mb =~ tr/A-Za-z/0/s;
103                         $mb =~ s/\b(\d)\b/0$1/g;
104                         while (length($ma) < length($mb)) { $ma .= ".00"; }
105                         while (length($mb) < length($ma)) { $mb .= ".00"; }
106                         # Comparison deliberately backwards
107                         $mb cmp $ma;} @fullname)[0];
108             } elsif (-f ($fullname="$thispth/lib$thislib.$so")
109                  && (($Config{'dlsrc'} ne "dl_dld.xs") || ($thislib eq "m"))){
110             } elsif (-f ($fullname="$thispth/lib${thislib}_s$Config_libext")
111                  && ($thislib .= "_s") ){ # we must explicitly use _s version
112             } elsif (-f ($fullname="$thispth/lib$thislib$Config_libext")){
113             } elsif (-f ($fullname="$thispth/$thislib$Config_libext")){
114             } elsif (-f ($fullname="$thispth/Slib$thislib$Config_libext")){
115             } elsif ($^O eq 'dgux'
116                  && -l ($fullname="$thispth/lib$thislib$Config_libext")
117                  && readlink($fullname) =~ /^elink:/) {
118                  # Some of DG's libraries look like misconnected symbolic
119                  # links, but development tools can follow them.  (They
120                  # look like this:
121                  #
122                  #    libm.a -> elink:${SDE_PATH:-/usr}/sde/\
123                  #    ${TARGET_BINARY_INTERFACE:-m88kdgux}/usr/lib/libm.a
124                  #
125                  # , the compilation tools expand the environment variables.)
126             } else {
127                 warn "$thislib not found in $thispth\n" if $verbose;
128                 next;
129             }
130             warn "'-l$thislib' found at $fullname\n" if $verbose;
131             my($fullnamedir) = dirname($fullname);
132             push @ld_run_path, $fullnamedir unless $ld_run_path_seen{$fullnamedir}++;
133             $found++;
134             $found_lib++;
135
136             # Now update library lists
137
138             # what do we know about this library...
139             my $is_dyna = ($fullname !~ /\Q$Config_libext\E$/);
140             my $in_perl = ($libs =~ /\B-l\Q$ {thislib}\E\b/s);
141
142             # Do not add it into the list if it is already linked in
143             # with the main perl executable.
144             # We have to special-case the NeXT, because math and ndbm 
145             # are both in libsys_s
146             unless ($in_perl || 
147                 ($Config{'osname'} eq 'next' &&
148                     ($thislib eq 'm' || $thislib eq 'ndbm')) ){
149                 push(@extralibs, "-l$thislib");
150             }
151
152             # We might be able to load this archive file dynamically
153             if ( ($Config{'dlsrc'} =~ /dl_next/ && $Config{'osvers'} lt '4_0')
154             ||   ($Config{'dlsrc'} =~ /dl_dld/) )
155             {
156                 # We push -l$thislib instead of $fullname because
157                 # it avoids hardwiring a fixed path into the .bs file.
158                 # Mkbootstrap will automatically add dl_findfile() to
159                 # the .bs file if it sees a name in the -l format.
160                 # USE THIS, when dl_findfile() is fixed: 
161                 # push(@bsloadlibs, "-l$thislib");
162                 # OLD USE WAS while checking results against old_extliblist
163                 push(@bsloadlibs, "$fullname");
164             } else {
165                 if ($is_dyna){
166                     # For SunOS4, do not add in this shared library if
167                     # it is already linked in the main perl executable
168                     push(@ldloadlibs, "-l$thislib")
169                         unless ($in_perl and $^O eq 'sunos');
170                 } else {
171                     push(@ldloadlibs, "-l$thislib");
172                 }
173             }
174             last;       # found one here so don't bother looking further
175         }
176         warn "Note (probably harmless): "
177                      ."No library found for -l$thislib\n"
178             unless $found_lib>0;
179     }
180     return ('','','','') unless $found;
181     ("@extralibs", "@bsloadlibs", "@ldloadlibs",join(":",@ld_run_path));
182 }
183
184 sub _win32_ext {
185
186     require Text::ParseWords;
187
188     my($self, $potential_libs, $verbose) = @_;
189
190     # If user did not supply a list, we punt.
191     # (caller should probably use the list in $Config{libs})
192     return ("", "", "", "") unless $potential_libs;
193
194     my $cc              = $Config{cc};
195     my $VC              = 1 if $cc =~ /^cl/i;
196     my $BC              = 1 if $cc =~ /^bcc/i;
197     my $GC              = 1 if $cc =~ /^gcc/i;
198     my $so              = $Config{'so'};
199     my $libs            = $Config{'libs'};
200     my $libpth          = $Config{'libpth'};
201     my $libext          = $Config{'lib_ext'} || ".lib";
202
203     if ($libs and $potential_libs !~ /:nodefault/i) { 
204         # If Config.pm defines a set of default libs, we always
205         # tack them on to the user-supplied list, unless the user
206         # specified :nodefault
207
208         $potential_libs .= " " if $potential_libs;
209         $potential_libs .= $libs;
210     }
211     warn "Potential libraries are '$potential_libs':\n" if $verbose;
212
213     # normalize to forward slashes
214     $libpth =~ s,\\,/,g;
215     $potential_libs =~ s,\\,/,g;
216
217     # compute $extralibs from $potential_libs
218
219     my @searchpath;                 # from "-L/path" in $potential_libs
220     my @libpath         = Text::ParseWords::quotewords('\s+', 0, $libpth);
221     my @extralibs;
222     my $pwd             = cwd();    # from Cwd.pm
223     my $lib             = '';
224     my $found           = 0;
225     my $search          = 1;
226     my($fullname, $thislib, $thispth);
227
228     # add "$Config{installarchlib}/CORE" to default search path
229     push @libpath, "$Config{installarchlib}/CORE";
230
231     foreach (Text::ParseWords::quotewords('\s+', 0, $potential_libs)){
232
233         $thislib = $_;
234
235         # see if entry is a flag
236         if (/^:\w+$/) {
237             $search     = 0 if lc eq ':nosearch';
238             $search     = 1 if lc eq ':search';
239             warn "Ignoring unknown flag '$thislib'\n"
240                 if $verbose and !/^:(no)?(search|default)$/i;
241             next;
242         }
243
244         # if searching is disabled, do compiler-specific translations
245         unless ($search) {
246             s/^-l(.+)$/$1.lib/ unless $GC;
247             s/^-L/-libpath:/ if $VC;
248             push(@extralibs, $_);
249             $found++;
250             next;
251         }
252
253         # handle possible linker path arguments
254         if (s/^-L// and not -d) {
255             warn "$thislib ignored, directory does not exist\n"
256                 if $verbose;
257             next;
258         }
259         elsif (-d) {
260             unless ($self->file_name_is_absolute($_)) {
261               warn "Warning: '$thislib' changed to '-L$pwd/$_'\n";
262               $_ = $self->catdir($pwd,$_);
263             }
264             push(@searchpath, $_);
265             next;
266         }
267
268         # handle possible library arguments
269         if (s/^-l// and $GC and !/^lib/i) {
270             $_ = "lib$_";
271         }
272         $_ .= $libext if !/\Q$libext\E$/i;
273
274         my $secondpass = 0;
275     LOOKAGAIN:
276
277         # look for the file itself
278         if (-f) {
279             warn "'$thislib' found as '$_'\n" if $verbose;
280             $found++;
281             push(@extralibs, $_);
282             next;
283         }
284
285         my $found_lib = 0;
286         foreach $thispth (@searchpath, @libpath){
287             unless (-f ($fullname="$thispth\\$_")) {
288                 warn "'$thislib' not found as '$fullname'\n" if $verbose;
289                 next;
290             }
291             warn "'$thislib' found as '$fullname'\n" if $verbose;
292             $found++;
293             $found_lib++;
294             push(@extralibs, $fullname);
295             last;
296         }
297
298         # do another pass with (or without) leading 'lib' if they used -l
299         if (!$found_lib and $thislib =~ /^-l/ and !$secondpass++) {
300             if ($GC) {
301                 goto LOOKAGAIN if s/^lib//i;
302             }
303             elsif (!/^lib/i) {
304                 $_ = "lib$_";
305                 goto LOOKAGAIN;
306             }
307         }
308
309         # give up
310         warn "Note (probably harmless): "
311                      ."No library found for '$thislib'\n"
312             unless $found_lib>0;
313
314     }
315
316     return ('','','','') unless $found;
317
318     # make sure paths with spaces are properly quoted
319     @extralibs = map { (/\s/ && !/^".*"$/) ? qq["$_"] : $_ } @extralibs;
320     $lib = join(' ',@extralibs);
321
322     # normalize back to backward slashes (to help braindead tools)
323     # XXX this may break equally braindead GNU tools that don't understand
324     # backslashes, either.  Seems like one can't win here.  Cursed be CP/M.
325     $lib =~ s,/,\\,g;
326
327     warn "Result: $lib\n" if $verbose;
328     wantarray ? ($lib, '', $lib, '') : $lib;
329 }
330
331
332 sub _vms_ext {
333   my($self, $potential_libs,$verbose) = @_;
334   my(@crtls,$crtlstr);
335   my($dbgqual) = $self->{OPTIMIZE} || $Config{'optimize'} ||
336                  $self->{CCFLAS}   || $Config{'ccflags'};
337   @crtls = ( ($dbgqual =~ m-/Debug-i ? $Config{'dbgprefix'} : '')
338               . 'PerlShr/Share' );
339   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libs'});
340   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libc'});
341   # In general, we pass through the basic libraries from %Config unchanged.
342   # The one exception is that if we're building in the Perl source tree, and
343   # a library spec could be resolved via a logical name, we go to some trouble
344   # to insure that the copy in the local tree is used, rather than one to
345   # which a system-wide logical may point.
346   if ($self->{PERL_SRC}) {
347     my($lib,$locspec,$type);
348     foreach $lib (@crtls) { 
349       if (($locspec,$type) = $lib =~ m-^([\w$\-]+)(/\w+)?- and $locspec =~ /perl/i) {
350         if    (lc $type eq '/share')   { $locspec .= $Config{'exe_ext'}; }
351         elsif (lc $type eq '/library') { $locspec .= $Config{'lib_ext'}; }
352         else                           { $locspec .= $Config{'obj_ext'}; }
353         $locspec = $self->catfile($self->{PERL_SRC},$locspec);
354         $lib = "$locspec$type" if -e $locspec;
355       }
356     }
357   }
358   $crtlstr = @crtls ? join(' ',@crtls) : '';
359
360   unless ($potential_libs) {
361     warn "Result:\n\tEXTRALIBS: \n\tLDLOADLIBS: $crtlstr\n" if $verbose;
362     return ('', '', $crtlstr, '');
363   }
364
365   my(@dirs,@libs,$dir,$lib,%sh,%olb,%obj,$ldlib);
366   my $cwd = cwd();
367   my($so,$lib_ext,$obj_ext) = @Config{'so','lib_ext','obj_ext'};
368   # List of common Unix library names and there VMS equivalents
369   # (VMS equivalent of '' indicates that the library is automatially
370   # searched by the linker, and should be skipped here.)
371   my %libmap = ( 'm' => '', 'f77' => '', 'F77' => '', 'V77' => '', 'c' => '',
372                  'malloc' => '', 'crypt' => '', 'resolv' => '', 'c_s' => '',
373                  'socket' => '', 'X11' => 'DECW$XLIBSHR',
374                  'Xt' => 'DECW$XTSHR', 'Xm' => 'DECW$XMLIBSHR',
375                  'Xmu' => 'DECW$XMULIBSHR');
376   if ($Config{'vms_cc_type'} ne 'decc') { $libmap{'curses'} = 'VAXCCURSE'; }
377
378   warn "Potential libraries are '$potential_libs'\n" if $verbose;
379
380   # First, sort out directories and library names in the input
381   foreach $lib (split ' ',$potential_libs) {
382     push(@dirs,$1),   next if $lib =~ /^-L(.*)/;
383     push(@dirs,$lib), next if $lib =~ /[:>\]]$/;
384     push(@dirs,$lib), next if -d $lib;
385     push(@libs,$1),   next if $lib =~ /^-l(.*)/;
386     push(@libs,$lib);
387   }
388   push(@dirs,split(' ',$Config{'libpth'}));
389
390   # Now make sure we've got VMS-syntax absolute directory specs
391   # (We don't, however, check whether someone's hidden a relative
392   # path in a logical name.)
393   foreach $dir (@dirs) {
394     unless (-d $dir) {
395       warn "Skipping nonexistent Directory $dir\n" if $verbose > 1;
396       $dir = '';
397       next;
398     }
399     warn "Resolving directory $dir\n" if $verbose;
400     if ($self->file_name_is_absolute($dir)) { $dir = $self->fixpath($dir,1); }
401     else                                    { $dir = $self->catdir($cwd,$dir); }
402   }
403   @dirs = grep { length($_) } @dirs;
404   unshift(@dirs,''); # Check each $lib without additions first
405
406   LIB: foreach $lib (@libs) {
407     if (exists $libmap{$lib}) {
408       next unless length $libmap{$lib};
409       $lib = $libmap{$lib};
410     }
411
412     my(@variants,$variant,$name,$test,$cand);
413     my($ctype) = '';
414
415     # If we don't have a file type, consider it a possibly abbreviated name and
416     # check for common variants.  We try these first to grab libraries before
417     # a like-named executable image (e.g. -lperl resolves to perlshr.exe
418     # before perl.exe).
419     if ($lib !~ /\.[^:>\]]*$/) {
420       push(@variants,"${lib}shr","${lib}rtl","${lib}lib");
421       push(@variants,"lib$lib") if $lib !~ /[:>\]]/;
422     }
423     push(@variants,$lib);
424     warn "Looking for $lib\n" if $verbose;
425     foreach $variant (@variants) {
426       foreach $dir (@dirs) {
427         my($type);
428
429         $name = "$dir$variant";
430         warn "\tChecking $name\n" if $verbose > 2;
431         if (-f ($test = VMS::Filespec::rmsexpand($name))) {
432           # It's got its own suffix, so we'll have to figure out the type
433           if    ($test =~ /(?:$so|exe)$/i)      { $type = 'sh'; }
434           elsif ($test =~ /(?:$lib_ext|olb)$/i) { $type = 'olb'; }
435           elsif ($test =~ /(?:$obj_ext|obj)$/i) {
436             warn "Note (probably harmless): "
437                          ."Plain object file $test found in library list\n";
438             $type = 'obj';
439           }
440           else {
441             warn "Note (probably harmless): "
442                          ."Unknown library type for $test; assuming shared\n";
443             $type = 'sh';
444           }
445         }
446         elsif (-f ($test = VMS::Filespec::rmsexpand($name,$so))      or
447                -f ($test = VMS::Filespec::rmsexpand($name,'.exe')))     {
448           $type = 'sh';
449           $name = $test unless $test =~ /exe;?\d*$/i;
450         }
451         elsif (not length($ctype) and  # If we've got a lib already, don't bother
452                ( -f ($test = VMS::Filespec::rmsexpand($name,$lib_ext)) or
453                  -f ($test = VMS::Filespec::rmsexpand($name,'.olb'))))  {
454           $type = 'olb';
455           $name = $test unless $test =~ /olb;?\d*$/i;
456         }
457         elsif (not length($ctype) and  # If we've got a lib already, don't bother
458                ( -f ($test = VMS::Filespec::rmsexpand($name,$obj_ext)) or
459                  -f ($test = VMS::Filespec::rmsexpand($name,'.obj'))))  {
460           warn "Note (probably harmless): "
461                        ."Plain object file $test found in library list\n";
462           $type = 'obj';
463           $name = $test unless $test =~ /obj;?\d*$/i;
464         }
465         if (defined $type) {
466           $ctype = $type; $cand = $name;
467           last if $ctype eq 'sh';
468         }
469       }
470       if ($ctype) { 
471         eval '$' . $ctype . "{'$cand'}++";
472         die "Error recording library: $@" if $@;
473         warn "\tFound as $cand (really $test), type $ctype\n" if $verbose > 1;
474         next LIB;
475       }
476     }
477     warn "Note (probably harmless): "
478                  ."No library found for $lib\n";
479   }
480
481   @libs = sort keys %obj;
482   # This has to precede any other CRTLs, so just make it first
483   if ($olb{VAXCCURSE}) {
484     push(@libs,"$olb{VAXCCURSE}/Library");
485     delete $olb{VAXCCURSE};
486   }
487   push(@libs, map { "$_/Library" } sort keys %olb);
488   push(@libs, map { "$_/Share"   } sort keys %sh);
489   $lib = join(' ',@libs);
490
491   $ldlib = $crtlstr ? "$lib $crtlstr" : $lib;
492   warn "Result:\n\tEXTRALIBS: $lib\n\tLDLOADLIBS: $ldlib\n" if $verbose;
493   wantarray ? ($lib, '', $ldlib, '') : $lib;
494 }
495
496 1;
497
498 __END__
499
500 =head1 NAME
501
502 ExtUtils::Liblist - determine libraries to use and how to use them
503
504 =head1 SYNOPSIS
505
506 C<require ExtUtils::Liblist;>
507
508 C<ExtUtils::Liblist::ext($self, $potential_libs, $verbose);>
509
510 =head1 DESCRIPTION
511
512 This utility takes a list of libraries in the form C<-llib1 -llib2
513 -llib3> and prints out lines suitable for inclusion in an extension
514 Makefile.  Extra library paths may be included with the form
515 C<-L/another/path> this will affect the searches for all subsequent
516 libraries.
517
518 It returns an array of four scalar values: EXTRALIBS, BSLOADLIBS,
519 LDLOADLIBS, and LD_RUN_PATH.  Some of these don't mean anything
520 on VMS and Win32.  See the details about those platform specifics
521 below.
522
523 Dependent libraries can be linked in one of three ways:
524
525 =over 2
526
527 =item * For static extensions
528
529 by the ld command when the perl binary is linked with the extension
530 library. See EXTRALIBS below.
531
532 =item * For dynamic extensions
533
534 by the ld command when the shared object is built/linked. See
535 LDLOADLIBS below.
536
537 =item * For dynamic extensions
538
539 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
540 below.
541
542 =back
543
544 =head2 EXTRALIBS
545
546 List of libraries that need to be linked with when linking a perl
547 binary which includes this extension Only those libraries that
548 actually exist are included.  These are written to a file and used
549 when linking perl.
550
551 =head2 LDLOADLIBS and LD_RUN_PATH
552
553 List of those libraries which can or must be linked into the shared
554 library when created using ld. These may be static or dynamic
555 libraries.  LD_RUN_PATH is a colon separated list of the directories
556 in LDLOADLIBS. It is passed as an environment variable to the process
557 that links the shared library.
558
559 =head2 BSLOADLIBS
560
561 List of those libraries that are needed but can be linked in
562 dynamically at run time on this platform.  SunOS/Solaris does not need
563 this because ld records the information (from LDLOADLIBS) into the
564 object file.  This list is used to create a .bs (bootstrap) file.
565
566 =head1 PORTABILITY
567
568 This module deals with a lot of system dependencies and has quite a
569 few architecture specific B<if>s in the code.
570
571 =head2 VMS implementation
572
573 The version of ext() which is executed under VMS differs from the
574 Unix-OS/2 version in several respects:
575
576 =over 2
577
578 =item *
579
580 Input library and path specifications are accepted with or without the
581 C<-l> and C<-L> prefices used by Unix linkers.  If neither prefix is
582 present, a token is considered a directory to search if it is in fact
583 a directory, and a library to search for otherwise.  Authors who wish
584 their extensions to be portable to Unix or OS/2 should use the Unix
585 prefixes, since the Unix-OS/2 version of ext() requires them.
586
587 =item *
588
589 Wherever possible, shareable images are preferred to object libraries,
590 and object libraries to plain object files.  In accordance with VMS
591 naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
592 it also looks for I<lib>lib and libI<lib> to accomodate Unix conventions
593 used in some ported software.
594
595 =item *
596
597 For each library that is found, an appropriate directive for a linker options
598 file is generated.  The return values are space-separated strings of
599 these directives, rather than elements used on the linker command line.
600
601 =item *
602
603 LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
604 the CRTLs, if any, specified in Config.pm.  EXTRALIBS contains just those
605 libraries found based on C<$potential_libs>.  BSLOADLIBS and LD_RUN_PATH
606 are always empty.
607
608 =back
609
610 In addition, an attempt is made to recognize several common Unix library
611 names, and filter them out or convert them to their VMS equivalents, as
612 appropriate.
613
614 In general, the VMS version of ext() should properly handle input from
615 extensions originally designed for a Unix or VMS environment.  If you
616 encounter problems, or discover cases where the search could be improved,
617 please let us know.
618
619 =head2 Win32 implementation
620
621 The version of ext() which is executed under Win32 differs from the
622 Unix-OS/2 version in several respects:
623
624 =over 2
625
626 =item *
627
628 If C<$potential_libs> is empty, the return value will be empty.
629 Otherwise, the libraries specified by C<$Config{libs}> (see Config.pm)
630 will be appended to the list of C<$potential_libs>.  The libraries
631 will be searched for in the directories specified in C<$potential_libs>,
632 C<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
633 For each library that is found,  a space-separated list of fully qualified
634 library pathnames is generated.
635
636 =item *
637
638 Input library and path specifications are accepted with or without the
639 C<-l> and C<-L> prefices used by Unix linkers.
640
641 An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
642 for the libraries that follow.
643
644 An entry of the form C<-lfoo> specifies the library C<foo>, which may be
645 spelled differently depending on what kind of compiler you are using.  If
646 you are using GCC, it gets translated to C<libfoo.a>, but for other win32
647 compilers, it becomes C<foo.lib>.  If no files are found by those translated
648 names, one more attempt is made to find them using either C<foo.a> or
649 C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
650 being used, respectively.
651
652 If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
653 considered a directory to search if it is in fact a directory, and a
654 library to search for otherwise.  The C<$Config{lib_ext}> suffix will
655 be appended to any entries that are not directories and don't already have
656 the suffix.
657
658 Note that the C<-L> and <-l> prefixes are B<not required>, but authors
659 who wish their extensions to be portable to Unix or OS/2 should use the
660 prefixes, since the Unix-OS/2 version of ext() requires them.
661
662 =item *
663
664 Entries cannot be plain object files, as many Win32 compilers will
665 not handle object files in the place of libraries.
666
667 =item *
668
669 Entries in C<$potential_libs> beginning with a colon and followed by
670 alphanumeric characters are treated as flags.  Unknown flags will be ignored.
671
672 An entry that matches C</:nodefault/i> disables the appending of default
673 libraries found in C<$Config{libs}> (this should be only needed very rarely).
674
675 An entry that matches C</:nosearch/i> disables all searching for
676 the libraries specified after it.  Translation of C<-Lfoo> and
677 C<-lfoo> still happens as appropriate (depending on compiler being used,
678 as reflected by C<$Config{cc}>), but the entries are not verified to be
679 valid files or directories.
680
681 An entry that matches C</:search/i> reenables searching for
682 the libraries specified after it.  You can put it at the end to
683 enable searching for default libraries specified by C<$Config{libs}>.
684
685 =item *
686
687 The libraries specified may be a mixture of static libraries and
688 import libraries (to link with DLLs).  Since both kinds are used
689 pretty transparently on the win32 platform, we do not attempt to
690 distinguish between them.
691
692 =item *
693
694 LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
695 and LD_RUN_PATH are always empty (this may change in future).
696
697 =item *
698
699 You must make sure that any paths and path components are properly
700 surrounded with double-quotes if they contain spaces. For example,
701 C<$potential_libs> could be (literally):
702
703         "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
704
705 Note how the first and last entries are protected by quotes in order
706 to protect the spaces.
707
708 =item *
709
710 Since this module is most often used only indirectly from extension
711 C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
712 a library to the build process for an extension:
713
714         LIBS => ['-lgl']
715
716 When using GCC, that entry specifies that MakeMaker should first look
717 for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
718 C<$Config{libpth}>.
719
720 When using a compiler other than GCC, the above entry will search for
721 C<gl.lib> (followed by C<libgl.lib>).
722
723 If the library happens to be in a location not in C<$Config{libpth}>,
724 you need:
725
726         LIBS => ['-Lc:\gllibs -lgl']
727
728 Here is a less often used example:
729
730         LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
731
732 This specifies a search for library C<gl> as before.  If that search
733 fails to find the library, it looks at the next item in the list. The
734 C<:nosearch> flag will prevent searching for the libraries that follow,
735 so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
736 since GCC can use that value as is with its linker.
737
738 When using the Visual C compiler, the second item is returned as
739 C<-libpath:d:\mesalibs mesa.lib user32.lib>.
740
741 When using the Borland compiler, the second item is returned as
742 C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
743 moving the C<-Ld:\mesalibs> to the correct place in the linker
744 command line.
745
746 =back
747
748
749 =head1 SEE ALSO
750
751 L<ExtUtils::MakeMaker>
752
753 =cut
754