lib/ExtUtils/Liblist.pm

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