lib/ExtUtils/Liblist.pm

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