lib/ExtUtils/Liblist.pm

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