lib/ExtUtils/Liblist.pm

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