contrib/perl5/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.1.1.2 $, 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> prefixes 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 accommodate 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> prefixes 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 C<-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