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