This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
b072c1292c7ff0424df734afc22c56ea800c3123
[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     foreach (Text::ParseWords::quotewords('\s+', 0, $potential_libs)){
229
230         $thislib = $_;
231
232         # see if entry is a flag
233         if (/^:\w+$/) {
234             $search     = 0 if lc eq ':nosearch';
235             $search     = 1 if lc eq ':search';
236             warn "Ignoring unknown flag '$thislib'\n"
237                 if $verbose and !/^:(no)?(search|default)$/i;
238             next;
239         }
240
241         # if searching is disabled, do compiler-specific translations
242         unless ($search) {
243             s/^-L/-libpath:/ if $VC;
244             s/^-l(.+)$/$1.lib/ unless $GC;
245             push(@extralibs, $_);
246             $found++;
247             next;
248         }
249
250         # handle possible linker path arguments
251         if (s/^-L// and not -d) {
252             warn "$thislib ignored, directory does not exist\n"
253                 if $verbose;
254             next;
255         }
256         elsif (-d) {
257             unless ($self->file_name_is_absolute($_)) {
258               warn "Warning: '$thislib' changed to '-L$pwd/$_'\n";
259               $_ = $self->catdir($pwd,$_);
260             }
261             push(@searchpath, $_);
262             next;
263         }
264
265         # handle possible library arguments
266         if (s/^-l// and $GC and !/^lib/i) {
267             $_ = "lib$_";
268         }
269         $_ .= $libext if !/\Q$libext\E$/i;
270
271         my $secondpass = 0;
272     LOOKAGAIN:
273
274         # look for the file itself
275         if (-f) {
276             warn "'$thislib' found as '$_'\n" if $verbose;
277             $found++;
278             push(@extralibs, $_);
279             next;
280         }
281
282         my $found_lib = 0;
283         foreach $thispth (@searchpath, @libpath){
284             unless (-f ($fullname="$thispth\\$_")) {
285                 warn "'$thislib' not found as '$fullname'\n" if $verbose;
286                 next;
287             }
288             warn "'$thislib' found as '$fullname'\n" if $verbose;
289             $found++;
290             $found_lib++;
291             push(@extralibs, $fullname);
292             last;
293         }
294
295         # do another pass with (or without) leading 'lib' if they used -l
296         if (!$found_lib and $thislib =~ /^-l/ and !$secondpass++) {
297             if ($GC) {
298                 goto LOOKAGAIN if s/^lib//i;
299             }
300             elsif (!/^lib/i) {
301                 $_ = "lib$_";
302                 goto LOOKAGAIN;
303             }
304         }
305
306         # give up
307         warn "Note (probably harmless): "
308                      ."No library found for '$thislib'\n"
309             unless $found_lib>0;
310
311     }
312
313     return ('','','','') unless $found;
314
315     # make sure paths with spaces are properly quoted
316     @extralibs = map { (/\s/ && !/^".*"$/) ? qq["$_"] : $_ } @extralibs;
317     $lib = join(' ',@extralibs);
318
319     # normalize back to backward slashes (to help braindead tools)
320     # XXX this may break equally braindead GNU tools that don't understand
321     # backslashes, either.  Seems like one can't win here.  Cursed be CP/M.
322     $lib =~ s,/,\\,g;
323
324     warn "Result: $lib\n" if $verbose;
325     wantarray ? ($lib, '', $lib, '') : $lib;
326 }
327
328
329 sub _vms_ext {
330   my($self, $potential_libs,$verbose) = @_;
331   my(@crtls,$crtlstr);
332   my($dbgqual) = $self->{OPTIMIZE} || $Config{'optimize'} ||
333                  $self->{CCFLAS}   || $Config{'ccflags'};
334   @crtls = ( ($dbgqual =~ m-/Debug-i ? $Config{'dbgprefix'} : '')
335               . 'PerlShr/Share' );
336   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libs'});
337   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libc'});
338   # In general, we pass through the basic libraries from %Config unchanged.
339   # The one exception is that if we're building in the Perl source tree, and
340   # a library spec could be resolved via a logical name, we go to some trouble
341   # to insure that the copy in the local tree is used, rather than one to
342   # which a system-wide logical may point.
343   if ($self->{PERL_SRC}) {
344     my($lib,$locspec,$type);
345     foreach $lib (@crtls) { 
346       if (($locspec,$type) = $lib =~ m-^([\w$\-]+)(/\w+)?- and $locspec =~ /perl/i) {
347         if    (lc $type eq '/share')   { $locspec .= $Config{'exe_ext'}; }
348         elsif (lc $type eq '/library') { $locspec .= $Config{'lib_ext'}; }
349         else                           { $locspec .= $Config{'obj_ext'}; }
350         $locspec = $self->catfile($self->{PERL_SRC},$locspec);
351         $lib = "$locspec$type" if -e $locspec;
352       }
353     }
354   }
355   $crtlstr = @crtls ? join(' ',@crtls) : '';
356
357   unless ($potential_libs) {
358     warn "Result:\n\tEXTRALIBS: \n\tLDLOADLIBS: $crtlstr\n" if $verbose;
359     return ('', '', $crtlstr, '');
360   }
361
362   my(@dirs,@libs,$dir,$lib,%sh,%olb,%obj,$ldlib);
363   my $cwd = cwd();
364   my($so,$lib_ext,$obj_ext) = @Config{'so','lib_ext','obj_ext'};
365   # List of common Unix library names and there VMS equivalents
366   # (VMS equivalent of '' indicates that the library is automatially
367   # searched by the linker, and should be skipped here.)
368   my %libmap = ( 'm' => '', 'f77' => '', 'F77' => '', 'V77' => '', 'c' => '',
369                  'malloc' => '', 'crypt' => '', 'resolv' => '', 'c_s' => '',
370                  'socket' => '', 'X11' => 'DECW$XLIBSHR',
371                  'Xt' => 'DECW$XTSHR', 'Xm' => 'DECW$XMLIBSHR',
372                  'Xmu' => 'DECW$XMULIBSHR');
373   if ($Config{'vms_cc_type'} ne 'decc') { $libmap{'curses'} = 'VAXCCURSE'; }
374
375   warn "Potential libraries are '$potential_libs'\n" if $verbose;
376
377   # First, sort out directories and library names in the input
378   foreach $lib (split ' ',$potential_libs) {
379     push(@dirs,$1),   next if $lib =~ /^-L(.*)/;
380     push(@dirs,$lib), next if $lib =~ /[:>\]]$/;
381     push(@dirs,$lib), next if -d $lib;
382     push(@libs,$1),   next if $lib =~ /^-l(.*)/;
383     push(@libs,$lib);
384   }
385   push(@dirs,split(' ',$Config{'libpth'}));
386
387   # Now make sure we've got VMS-syntax absolute directory specs
388   # (We don't, however, check whether someone's hidden a relative
389   # path in a logical name.)
390   foreach $dir (@dirs) {
391     unless (-d $dir) {
392       warn "Skipping nonexistent Directory $dir\n" if $verbose > 1;
393       $dir = '';
394       next;
395     }
396     warn "Resolving directory $dir\n" if $verbose;
397     if ($self->file_name_is_absolute($dir)) { $dir = $self->fixpath($dir,1); }
398     else                                    { $dir = $self->catdir($cwd,$dir); }
399   }
400   @dirs = grep { length($_) } @dirs;
401   unshift(@dirs,''); # Check each $lib without additions first
402
403   LIB: foreach $lib (@libs) {
404     if (exists $libmap{$lib}) {
405       next unless length $libmap{$lib};
406       $lib = $libmap{$lib};
407     }
408
409     my(@variants,$variant,$name,$test,$cand);
410     my($ctype) = '';
411
412     # If we don't have a file type, consider it a possibly abbreviated name and
413     # check for common variants.  We try these first to grab libraries before
414     # a like-named executable image (e.g. -lperl resolves to perlshr.exe
415     # before perl.exe).
416     if ($lib !~ /\.[^:>\]]*$/) {
417       push(@variants,"${lib}shr","${lib}rtl","${lib}lib");
418       push(@variants,"lib$lib") if $lib !~ /[:>\]]/;
419     }
420     push(@variants,$lib);
421     warn "Looking for $lib\n" if $verbose;
422     foreach $variant (@variants) {
423       foreach $dir (@dirs) {
424         my($type);
425
426         $name = "$dir$variant";
427         warn "\tChecking $name\n" if $verbose > 2;
428         if (-f ($test = VMS::Filespec::rmsexpand($name))) {
429           # It's got its own suffix, so we'll have to figure out the type
430           if    ($test =~ /(?:$so|exe)$/i)      { $type = 'sh'; }
431           elsif ($test =~ /(?:$lib_ext|olb)$/i) { $type = 'olb'; }
432           elsif ($test =~ /(?:$obj_ext|obj)$/i) {
433             warn "Note (probably harmless): "
434                          ."Plain object file $test found in library list\n";
435             $type = 'obj';
436           }
437           else {
438             warn "Note (probably harmless): "
439                          ."Unknown library type for $test; assuming shared\n";
440             $type = 'sh';
441           }
442         }
443         elsif (-f ($test = VMS::Filespec::rmsexpand($name,$so))      or
444                -f ($test = VMS::Filespec::rmsexpand($name,'.exe')))     {
445           $type = 'sh';
446           $name = $test unless $test =~ /exe;?\d*$/i;
447         }
448         elsif (not length($ctype) and  # If we've got a lib already, don't bother
449                ( -f ($test = VMS::Filespec::rmsexpand($name,$lib_ext)) or
450                  -f ($test = VMS::Filespec::rmsexpand($name,'.olb'))))  {
451           $type = 'olb';
452           $name = $test unless $test =~ /olb;?\d*$/i;
453         }
454         elsif (not length($ctype) and  # If we've got a lib already, don't bother
455                ( -f ($test = VMS::Filespec::rmsexpand($name,$obj_ext)) or
456                  -f ($test = VMS::Filespec::rmsexpand($name,'.obj'))))  {
457           warn "Note (probably harmless): "
458                        ."Plain object file $test found in library list\n";
459           $type = 'obj';
460           $name = $test unless $test =~ /obj;?\d*$/i;
461         }
462         if (defined $type) {
463           $ctype = $type; $cand = $name;
464           last if $ctype eq 'sh';
465         }
466       }
467       if ($ctype) { 
468         eval '$' . $ctype . "{'$cand'}++";
469         die "Error recording library: $@" if $@;
470         warn "\tFound as $cand (really $test), type $ctype\n" if $verbose > 1;
471         next LIB;
472       }
473     }
474     warn "Note (probably harmless): "
475                  ."No library found for $lib\n";
476   }
477
478   @libs = sort keys %obj;
479   # This has to precede any other CRTLs, so just make it first
480   if ($olb{VAXCCURSE}) {
481     push(@libs,"$olb{VAXCCURSE}/Library");
482     delete $olb{VAXCCURSE};
483   }
484   push(@libs, map { "$_/Library" } sort keys %olb);
485   push(@libs, map { "$_/Share"   } sort keys %sh);
486   $lib = join(' ',@libs);
487
488   $ldlib = $crtlstr ? "$lib $crtlstr" : $lib;
489   warn "Result:\n\tEXTRALIBS: $lib\n\tLDLOADLIBS: $ldlib\n" if $verbose;
490   wantarray ? ($lib, '', $ldlib, '') : $lib;
491 }
492
493 1;
494
495 __END__
496
497 =head1 NAME
498
499 ExtUtils::Liblist - determine libraries to use and how to use them
500
501 =head1 SYNOPSIS
502
503 C<require ExtUtils::Liblist;>
504
505 C<ExtUtils::Liblist::ext($self, $potential_libs, $verbose);>
506
507 =head1 DESCRIPTION
508
509 This utility takes a list of libraries in the form C<-llib1 -llib2
510 -llib3> and prints out lines suitable for inclusion in an extension
511 Makefile.  Extra library paths may be included with the form
512 C<-L/another/path> this will affect the searches for all subsequent
513 libraries.
514
515 It returns an array of four scalar values: EXTRALIBS, BSLOADLIBS,
516 LDLOADLIBS, and LD_RUN_PATH.  Some of these don't mean anything
517 on VMS and Win32.  See the details about those platform specifics
518 below.
519
520 Dependent libraries can be linked in one of three ways:
521
522 =over 2
523
524 =item * For static extensions
525
526 by the ld command when the perl binary is linked with the extension
527 library. See EXTRALIBS below.
528
529 =item * For dynamic extensions
530
531 by the ld command when the shared object is built/linked. See
532 LDLOADLIBS below.
533
534 =item * For dynamic extensions
535
536 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
537 below.
538
539 =back
540
541 =head2 EXTRALIBS
542
543 List of libraries that need to be linked with when linking a perl
544 binary which includes this extension Only those libraries that
545 actually exist are included.  These are written to a file and used
546 when linking perl.
547
548 =head2 LDLOADLIBS and LD_RUN_PATH
549
550 List of those libraries which can or must be linked into the shared
551 library when created using ld. These may be static or dynamic
552 libraries.  LD_RUN_PATH is a colon separated list of the directories
553 in LDLOADLIBS. It is passed as an environment variable to the process
554 that links the shared library.
555
556 =head2 BSLOADLIBS
557
558 List of those libraries that are needed but can be linked in
559 dynamically at run time on this platform.  SunOS/Solaris does not need
560 this because ld records the information (from LDLOADLIBS) into the
561 object file.  This list is used to create a .bs (bootstrap) file.
562
563 =head1 PORTABILITY
564
565 This module deals with a lot of system dependencies and has quite a
566 few architecture specific B<if>s in the code.
567
568 =head2 VMS implementation
569
570 The version of ext() which is executed under VMS differs from the
571 Unix-OS/2 version in several respects:
572
573 =over 2
574
575 =item *
576
577 Input library and path specifications are accepted with or without the
578 C<-l> and C<-L> prefices used by Unix linkers.  If neither prefix is
579 present, a token is considered a directory to search if it is in fact
580 a directory, and a library to search for otherwise.  Authors who wish
581 their extensions to be portable to Unix or OS/2 should use the Unix
582 prefixes, since the Unix-OS/2 version of ext() requires them.
583
584 =item *
585
586 Wherever possible, shareable images are preferred to object libraries,
587 and object libraries to plain object files.  In accordance with VMS
588 naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
589 it also looks for I<lib>lib and libI<lib> to accomodate Unix conventions
590 used in some ported software.
591
592 =item *
593
594 For each library that is found, an appropriate directive for a linker options
595 file is generated.  The return values are space-separated strings of
596 these directives, rather than elements used on the linker command line.
597
598 =item *
599
600 LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
601 the CRTLs, if any, specified in Config.pm.  EXTRALIBS contains just those
602 libraries found based on C<$potential_libs>.  BSLOADLIBS and LD_RUN_PATH
603 are always empty.
604
605 =back
606
607 In addition, an attempt is made to recognize several common Unix library
608 names, and filter them out or convert them to their VMS equivalents, as
609 appropriate.
610
611 In general, the VMS version of ext() should properly handle input from
612 extensions originally designed for a Unix or VMS environment.  If you
613 encounter problems, or discover cases where the search could be improved,
614 please let us know.
615
616 =head2 Win32 implementation
617
618 The version of ext() which is executed under Win32 differs from the
619 Unix-OS/2 version in several respects:
620
621 =over 2
622
623 =item *
624
625 If C<$potential_libs> is empty, the return value will be empty.
626 Otherwise, the libraries specified by C<$Config{libs}> (see Config.pm)
627 will be appended to the list of C<$potential_libs>.  The libraries
628 will be searched for in the directories specified in C<$potential_libs>
629 as well as in C<$Config{libpth}>. For each library that is found,  a
630 space-separated list of fully qualified library pathnames is generated.
631
632 =item *
633
634 Input library and path specifications are accepted with or without the
635 C<-l> and C<-L> prefices used by Unix linkers.
636
637 An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
638 for the libraries that follow.
639
640 An entry of the form C<-lfoo> specifies the library C<foo>, which may be
641 spelled differently depending on what kind of compiler you are using.  If
642 you are using GCC, it gets translated to C<libfoo.a>, but for other win32
643 compilers, it becomes C<foo.lib>.  If no files are found by those translated
644 names, one more attempt is made to find them using either C<foo.a> or
645 C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
646 being used, respectively.
647
648 If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
649 considered a directory to search if it is in fact a directory, and a
650 library to search for otherwise.  The C<$Config{lib_ext}> suffix will
651 be appended to any entries that are not directories and don't already have
652 the suffix.
653
654 Note that the C<-L> and <-l> prefixes are B<not required>, but authors
655 who wish their extensions to be portable to Unix or OS/2 should use the
656 prefixes, since the Unix-OS/2 version of ext() requires them.
657
658 =item *
659
660 Entries cannot be plain object files, as many Win32 compilers will
661 not handle object files in the place of libraries.
662
663 =item *
664
665 Entries in C<$potential_libs> beginning with a colon and followed by
666 alphanumeric characters are treated as flags.  Unknown flags will be ignored.
667
668 An entry that matches C</:nodefault/i> disables the appending of default
669 libraries found in C<$Config{libs}> (this should be only needed very rarely).
670
671 An entry that matches C</:nosearch/i> disables all searching for
672 the libraries specified after it.  Translation of C<-Lfoo> and
673 C<-lfoo> still happens as appropriate (depending on compiler being used,
674 as reflected by C<$Config{cc}>), but the entries are not verified to be
675 valid files or directories.
676
677 An entry that matches C</:search/i> reenables searching for
678 the libraries specified after it.  You can put it at the end to
679 enable searching for default libraries specified by C<$Config{libs}>.
680
681 =item *
682
683 The libraries specified may be a mixture of static libraries and
684 import libraries (to link with DLLs).  Since both kinds are used
685 pretty transparently on the win32 platform, we do not attempt to
686 distinguish between them.
687
688 =item *
689
690 LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
691 and LD_RUN_PATH are always empty (this may change in future).
692
693 =item *
694
695 You must make sure that any paths and path components are properly
696 surrounded with double-quotes if they contain spaces. For example,
697 C<$potential_libs> could be (literally):
698
699         "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
700
701 Note how the first and last entries are protected by quotes in order
702 to protect the spaces.
703
704 =item *
705
706 Since this module is most often used only indirectly from extension
707 C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
708 a library to the build process for an extension:
709
710         LIBS => ['-lgl']
711
712 When using GCC, that entry specifies that MakeMaker should first look
713 for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
714 C<$Config{libpth}>.
715
716 When using a compiler other than GCC, the above entry will search for
717 C<gl.lib> (followed by C<libgl.lib>).
718
719 If the library happens to be in a location not in C<$Config{libpth}>,
720 you need:
721
722         LIBS => ['-Lc:\gllibs -lgl']
723
724 Here is a less often used example:
725
726         LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
727
728 This specifies a search for library C<gl> as before.  If that search
729 fails to find the library, it looks at the next item in the list. The
730 C<:nosearch> flag will prevent searching for the libraries that follow,
731 so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
732 since GCC can use that value as is with its linker.
733
734 When using the Visual C compiler, the second item is returned as
735 C<-libpath:d:\mesalibs mesa.lib user32.lib>.
736
737 When using the Borland compiler, the second item is returned as
738 C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
739 moving the C<-Ld:\mesalibs> to the correct place in the linker
740 command line.
741
742 =back
743
744
745 =head1 SEE ALSO
746
747 L<ExtUtils::MakeMaker>
748
749 =cut
750