lib/ExtUtils/Liblist.pm

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