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         my $secondpass = 0;
 272     LOOKAGAIN:
 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 (!$found_lib and $thislib =~ /^-l/ and !$secondpass++) {
 297             if ($GC) {
 298                 goto LOOKAGAIN if s/^lib//i;
 299             }
 300             elsif (!/^lib/i) {
 301                 $_ = "lib$_";
 302                 goto LOOKAGAIN;
 303             }
 304         }
 305
 306         # give up
 307         warn "Note (probably harmless): "
 308                      ."No library found for '$thislib'\n"
 309             unless $found_lib>0;
 310
 311     }
 312
 313     return ('','','','') unless $found;
 314
 315     # make sure paths with spaces are properly quoted
 316     @extralibs = map { (/\s/ && !/^".*"$/) ? qq["$_"] : $_ } @extralibs;
 317     $lib = join(' ',@extralibs);
 318
 319     # normalize back to backward slashes (to help braindead tools)
 320     # XXX this may break equally braindead GNU tools that don't understand
 321     # backslashes, either.  Seems like one can't win here.  Cursed be CP/M.
 322     $lib =~ s,/,\\,g;
 323
 324     warn "Result: $lib\n" if $verbose;
 325     wantarray ? ($lib, '', $lib, '') : $lib;
 326 }
 327
 328
 329 sub _vms_ext {
 330   my($self, $potential_libs,$verbose) = @_;
 331   my(@crtls,$crtlstr);
 332   my($dbgqual) = $self->{OPTIMIZE} || $Config{'optimize'} ||
 333                  $self->{CCFLAS}   || $Config{'ccflags'};
 334   @crtls = ( ($dbgqual =~ m-/Debug-i ? $Config{'dbgprefix'} : '')
 335               . 'PerlShr/Share' );
 336   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libs'});
 337   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libc'});
 338   # In general, we pass through the basic libraries from %Config unchanged.
 339   # The one exception is that if we're building in the Perl source tree, and
 340   # a library spec could be resolved via a logical name, we go to some trouble
 341   # to insure that the copy in the local tree is used, rather than one to
 342   # which a system-wide logical may point.
 343   if ($self->{PERL_SRC}) {
 344     my($lib,$locspec,$type);
 345     foreach $lib (@crtls) {
 346       if (($locspec,$type) = $lib =~ m-^([\w$\-]+)(/\w+)?- and $locspec =~ /perl/i) {
 347         if    (lc $type eq '/share')   { $locspec .= $Config{'exe_ext'}; }
 348         elsif (lc $type eq '/library') { $locspec .= $Config{'lib_ext'}; }
 349         else                           { $locspec .= $Config{'obj_ext'}; }
 350         $locspec = $self->catfile($self->{PERL_SRC},$locspec);
 351         $lib = "$locspec$type" if -e $locspec;
 352       }
 353     }
 354   }
 355   $crtlstr = @crtls ? join(' ',@crtls) : '';
 356
 357   unless ($potential_libs) {
 358     warn "Result:\n\tEXTRALIBS: \n\tLDLOADLIBS: $crtlstr\n" if $verbose;
 359     return ('', '', $crtlstr, '');
 360   }
 361
 362   my(@dirs,@libs,$dir,$lib,%sh,%olb,%obj,$ldlib);
 363   my $cwd = cwd();
 364   my($so,$lib_ext,$obj_ext) = @Config{'so','lib_ext','obj_ext'};
 365   # List of common Unix library names and there VMS equivalents
 366   # (VMS equivalent of '' indicates that the library is automatially
 367   # searched by the linker, and should be skipped here.)
 368   my %libmap = ( 'm' => '', 'f77' => '', 'F77' => '', 'V77' => '', 'c' => '',
 369                  'malloc' => '', 'crypt' => '', 'resolv' => '', 'c_s' => '',
 370                  'socket' => '', 'X11' => 'DECW$XLIBSHR',
 371                  'Xt' => 'DECW$XTSHR', 'Xm' => 'DECW$XMLIBSHR',
 372                  'Xmu' => 'DECW$XMULIBSHR');
 373   if ($Config{'vms_cc_type'} ne 'decc') { $libmap{'curses'} = 'VAXCCURSE'; }
 374
 375   warn "Potential libraries are '$potential_libs'\n" if $verbose;
 376
 377   # First, sort out directories and library names in the input
 378   foreach $lib (split ' ',$potential_libs) {
 379     push(@dirs,$1),   next if $lib =~ /^-L(.*)/;
 380     push(@dirs,$lib), next if $lib =~ /[:>\]]$/;
 381     push(@dirs,$lib), next if -d $lib;
 382     push(@libs,$1),   next if $lib =~ /^-l(.*)/;
 383     push(@libs,$lib);
 384   }
 385   push(@dirs,split(' ',$Config{'libpth'}));
 386
 387   # Now make sure we've got VMS-syntax absolute directory specs
 388   # (We don't, however, check whether someone's hidden a relative
 389   # path in a logical name.)
 390   foreach $dir (@dirs) {
 391     unless (-d $dir) {
 392       warn "Skipping nonexistent Directory $dir\n" if $verbose > 1;
 393       $dir = '';
 394       next;
 395     }
 396     warn "Resolving directory $dir\n" if $verbose;
 397     if ($self->file_name_is_absolute($dir)) { $dir = $self->fixpath($dir,1); }
 398     else                                    { $dir = $self->catdir($cwd,$dir); }
 399   }
 400   @dirs = grep { length($_) } @dirs;
 401   unshift(@dirs,''); # Check each $lib without additions first
 402
 403   LIB: foreach $lib (@libs) {
 404     if (exists $libmap{$lib}) {
 405       next unless length $libmap{$lib};
 406       $lib = $libmap{$lib};
 407     }
 408
 409     my(@variants,$variant,$name,$test,$cand);
 410     my($ctype) = '';
 411
 412     # If we don't have a file type, consider it a possibly abbreviated name and
 413     # check for common variants.  We try these first to grab libraries before
 414     # a like-named executable image (e.g. -lperl resolves to perlshr.exe
 415     # before perl.exe).
 416     if ($lib !~ /\.[^:>\]]*$/) {
 417       push(@variants,"${lib}shr","${lib}rtl","${lib}lib");
 418       push(@variants,"lib$lib") if $lib !~ /[:>\]]/;
 419     }
 420     push(@variants,$lib);
 421     warn "Looking for $lib\n" if $verbose;
 422     foreach $variant (@variants) {
 423       foreach $dir (@dirs) {
 424         my($type);
 425
 426         $name = "$dir$variant";
 427         warn "\tChecking $name\n" if $verbose > 2;
 428         if (-f ($test = VMS::Filespec::rmsexpand($name))) {
 429           # It's got its own suffix, so we'll have to figure out the type
 430           if    ($test =~ /(?:$so|exe)$/i)      { $type = 'sh'; }
 431           elsif ($test =~ /(?:$lib_ext|olb)$/i) { $type = 'olb'; }
 432           elsif ($test =~ /(?:$obj_ext|obj)$/i) {
 433             warn "Note (probably harmless): "
 434                          ."Plain object file $test found in library list\n";
 435             $type = 'obj';
 436           }
 437           else {
 438             warn "Note (probably harmless): "
 439                          ."Unknown library type for $test; assuming shared\n";
 440             $type = 'sh';
 441           }
 442         }
 443         elsif (-f ($test = VMS::Filespec::rmsexpand($name,$so))      or
 444                -f ($test = VMS::Filespec::rmsexpand($name,'.exe')))     {
 445           $type = 'sh';
 446           $name = $test unless $test =~ /exe;?\d*$/i;
 447         }
 448         elsif (not length($ctype) and  # If we've got a lib already, don't bother
 449                ( -f ($test = VMS::Filespec::rmsexpand($name,$lib_ext)) or
 450                  -f ($test = VMS::Filespec::rmsexpand($name,'.olb'))))  {
 451           $type = 'olb';
 452           $name = $test unless $test =~ /olb;?\d*$/i;
 453         }
 454         elsif (not length($ctype) and  # If we've got a lib already, don't bother
 455                ( -f ($test = VMS::Filespec::rmsexpand($name,$obj_ext)) or
 456                  -f ($test = VMS::Filespec::rmsexpand($name,'.obj'))))  {
 457           warn "Note (probably harmless): "
 458                        ."Plain object file $test found in library list\n";
 459           $type = 'obj';
 460           $name = $test unless $test =~ /obj;?\d*$/i;
 461         }
 462         if (defined $type) {
 463           $ctype = $type; $cand = $name;
 464           last if $ctype eq 'sh';
 465         }
 466       }
 467       if ($ctype) {
 468         eval '$' . $ctype . "{'$cand'}++";
 469         die "Error recording library: $@" if $@;
 470         warn "\tFound as $cand (really $test), type $ctype\n" if $verbose > 1;
 471         next LIB;
 472       }
 473     }
 474     warn "Note (probably harmless): "
 475                  ."No library found for $lib\n";
 476   }
 477
 478   @libs = sort keys %obj;
 479   # This has to precede any other CRTLs, so just make it first
 480   if ($olb{VAXCCURSE}) {
 481     push(@libs,"$olb{VAXCCURSE}/Library");
 482     delete $olb{VAXCCURSE};
 483   }
 484   push(@libs, map { "$_/Library" } sort keys %olb);
 485   push(@libs, map { "$_/Share"   } sort keys %sh);
 486   $lib = join(' ',@libs);
 487
 488   $ldlib = $crtlstr ? "$lib $crtlstr" : $lib;
 489   warn "Result:\n\tEXTRALIBS: $lib\n\tLDLOADLIBS: $ldlib\n" if $verbose;
 490   wantarray ? ($lib, '', $ldlib, '') : $lib;
 491 }
 492
 493 1;
 494
 495 __END__
 496
 497 =head1 NAME
 498
 499 ExtUtils::Liblist - determine libraries to use and how to use them
 500
 501 =head1 SYNOPSIS
 502
 503 C<require ExtUtils::Liblist;>
 504
 505 C<ExtUtils::Liblist::ext($self, $potential_libs, $verbose);>
 506
 507 =head1 DESCRIPTION
 508
 509 This utility takes a list of libraries in the form C<-llib1 -llib2
 510 -llib3> and prints out lines suitable for inclusion in an extension
 511 Makefile.  Extra library paths may be included with the form
 512 C<-L/another/path> this will affect the searches for all subsequent
 513 libraries.
 514
 515 It returns an array of four scalar values: EXTRALIBS, BSLOADLIBS,
 516 LDLOADLIBS, and LD_RUN_PATH.  Some of these don't mean anything
 517 on VMS and Win32.  See the details about those platform specifics
 518 below.
 519
 520 Dependent libraries can be linked in one of three ways:
 521
 522 =over 2
 523
 524 =item * For static extensions
 525
 526 by the ld command when the perl binary is linked with the extension
 527 library. See EXTRALIBS below.
 528
 529 =item * For dynamic extensions
 530
 531 by the ld command when the shared object is built/linked. See
 532 LDLOADLIBS below.
 533
 534 =item * For dynamic extensions
 535
 536 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
 537 below.
 538
 539 =back
 540
 541 =head2 EXTRALIBS
 542
 543 List of libraries that need to be linked with when linking a perl
 544 binary which includes this extension Only those libraries that
 545 actually exist are included.  These are written to a file and used
 546 when linking perl.
 547
 548 =head2 LDLOADLIBS and LD_RUN_PATH
 549
 550 List of those libraries which can or must be linked into the shared
 551 library when created using ld. These may be static or dynamic
 552 libraries.  LD_RUN_PATH is a colon separated list of the directories
 553 in LDLOADLIBS. It is passed as an environment variable to the process
 554 that links the shared library.
 555
 556 =head2 BSLOADLIBS
 557
 558 List of those libraries that are needed but can be linked in
 559 dynamically at run time on this platform.  SunOS/Solaris does not need
 560 this because ld records the information (from LDLOADLIBS) into the
 561 object file.  This list is used to create a .bs (bootstrap) file.
 562
 563 =head1 PORTABILITY
 564
 565 This module deals with a lot of system dependencies and has quite a
 566 few architecture specific B<if>s in the code.
 567
 568 =head2 VMS implementation
 569
 570 The version of ext() which is executed under VMS differs from the
 571 Unix-OS/2 version in several respects:
 572
 573 =over 2
 574
 575 =item *
 576
 577 Input library and path specifications are accepted with or without the
 578 C<-l> and C<-L> prefices used by Unix linkers.  If neither prefix is
 579 present, a token is considered a directory to search if it is in fact
 580 a directory, and a library to search for otherwise.  Authors who wish
 581 their extensions to be portable to Unix or OS/2 should use the Unix
 582 prefixes, since the Unix-OS/2 version of ext() requires them.
 583
 584 =item *
 585
 586 Wherever possible, shareable images are preferred to object libraries,
 587 and object libraries to plain object files.  In accordance with VMS
 588 naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
 589 it also looks for I<lib>lib and libI<lib> to accomodate Unix conventions
 590 used in some ported software.
 591
 592 =item *
 593
 594 For each library that is found, an appropriate directive for a linker options
 595 file is generated.  The return values are space-separated strings of
 596 these directives, rather than elements used on the linker command line.
 597
 598 =item *
 599
 600 LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
 601 the CRTLs, if any, specified in Config.pm.  EXTRALIBS contains just those
 602 libraries found based on C<$potential_libs>.  BSLOADLIBS and LD_RUN_PATH
 603 are always empty.
 604
 605 =back
 606
 607 In addition, an attempt is made to recognize several common Unix library
 608 names, and filter them out or convert them to their VMS equivalents, as
 609 appropriate.
 610
 611 In general, the VMS version of ext() should properly handle input from
 612 extensions originally designed for a Unix or VMS environment.  If you
 613 encounter problems, or discover cases where the search could be improved,
 614 please let us know.
 615
 616 =head2 Win32 implementation
 617
 618 The version of ext() which is executed under Win32 differs from the
 619 Unix-OS/2 version in several respects:
 620
 621 =over 2
 622
 623 =item *
 624
 625 If C<$potential_libs> is empty, the return value will be empty.
 626 Otherwise, the libraries specified by C<$Config{libs}> (see Config.pm)
 627 will be appended to the list of C<$potential_libs>.  The libraries
 628 will be searched for in the directories specified in C<$potential_libs>
 629 as well as in C<$Config{libpth}>. For each library that is found,  a
 630 space-separated list of fully qualified library pathnames is generated.
 631
 632 =item *
 633
 634 Input library and path specifications are accepted with or without the
 635 C<-l> and C<-L> prefices used by Unix linkers.
 636
 637 An entry of the form C<-La:\foo> specifies the C<a:\foo> directory to look
 638 for the libraries that follow.
 639
 640 An entry of the form C<-lfoo> specifies the library C<foo>, which may be
 641 spelled differently depending on what kind of compiler you are using.  If
 642 you are using GCC, it gets translated to C<libfoo.a>, but for other win32
 643 compilers, it becomes C<foo.lib>.  If no files are found by those translated
 644 names, one more attempt is made to find them using either C<foo.a> or
 645 C<libfoo.lib>, depending on whether GCC or some other win32 compiler is
 646 being used, respectively.
 647
 648 If neither the C<-L> or C<-l> prefix is present in an entry, the entry is
 649 considered a directory to search if it is in fact a directory, and a
 650 library to search for otherwise.  The C<$Config{lib_ext}> suffix will
 651 be appended to any entries that are not directories and don't already have
 652 the suffix.
 653
 654 Note that the C<-L> and <-l> prefixes are B<not required>, but authors
 655 who wish their extensions to be portable to Unix or OS/2 should use the
 656 prefixes, since the Unix-OS/2 version of ext() requires them.
 657
 658 =item *
 659
 660 Entries cannot be plain object files, as many Win32 compilers will
 661 not handle object files in the place of libraries.
 662
 663 =item *
 664
 665 Entries in C<$potential_libs> beginning with a colon and followed by
 666 alphanumeric characters are treated as flags.  Unknown flags will be ignored.
 667
 668 An entry that matches C</:nodefault/i> disables the appending of default
 669 libraries found in C<$Config{libs}> (this should be only needed very rarely).
 670
 671 An entry that matches C</:nosearch/i> disables all searching for
 672 the libraries specified after it.  Translation of C<-Lfoo> and
 673 C<-lfoo> still happens as appropriate (depending on compiler being used,
 674 as reflected by C<$Config{cc}>), but the entries are not verified to be
 675 valid files or directories.
 676
 677 An entry that matches C</:search/i> reenables searching for
 678 the libraries specified after it.  You can put it at the end to
 679 enable searching for default libraries specified by C<$Config{libs}>.
 680
 681 =item *
 682
 683 The libraries specified may be a mixture of static libraries and
 684 import libraries (to link with DLLs).  Since both kinds are used
 685 pretty transparently on the win32 platform, we do not attempt to
 686 distinguish between them.
 687
 688 =item *
 689
 690 LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS
 691 and LD_RUN_PATH are always empty (this may change in future).
 692
 693 =item *
 694
 695 You must make sure that any paths and path components are properly
 696 surrounded with double-quotes if they contain spaces. For example,
 697 C<$potential_libs> could be (literally):
 698
 699         "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"
 700
 701 Note how the first and last entries are protected by quotes in order
 702 to protect the spaces.
 703
 704 =item *
 705
 706 Since this module is most often used only indirectly from extension
 707 C<Makefile.PL> files, here is an example C<Makefile.PL> entry to add
 708 a library to the build process for an extension:
 709
 710         LIBS => ['-lgl']
 711
 712 When using GCC, that entry specifies that MakeMaker should first look
 713 for C<libgl.a> (followed by C<gl.a>) in all the locations specified by
 714 C<$Config{libpth}>.
 715
 716 When using a compiler other than GCC, the above entry will search for
 717 C<gl.lib> (followed by C<libgl.lib>).
 718
 719 If the library happens to be in a location not in C<$Config{libpth}>,
 720 you need:
 721
 722         LIBS => ['-Lc:\gllibs -lgl']
 723
 724 Here is a less often used example:
 725
 726         LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']
 727
 728 This specifies a search for library C<gl> as before.  If that search
 729 fails to find the library, it looks at the next item in the list. The
 730 C<:nosearch> flag will prevent searching for the libraries that follow,
 731 so it simply returns the value as C<-Ld:\mesalibs -lmesa -luser32>,
 732 since GCC can use that value as is with its linker.
 733
 734 When using the Visual C compiler, the second item is returned as
 735 C<-libpath:d:\mesalibs mesa.lib user32.lib>.
 736
 737 When using the Borland compiler, the second item is returned as
 738 C<-Ld:\mesalibs mesa.lib user32.lib>, and MakeMaker takes care of
 739 moving the C<-Ld:\mesalibs> to the correct place in the linker
 740 command line.
 741
 742 =back
 743
 744
 745 =head1 SEE ALSO
 746
 747 L<ExtUtils::MakeMaker>
 748
 749 =cut
 750