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