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