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     # add "$Config{installarchlib}/CORE" to default search path
 229     push @libpath, "$Config{installarchlib}/CORE";
 230
 231     foreach (Text::ParseWords::quotewords('\s+', 0, $potential_libs)){
 232
 233         $thislib = $_;
 234
 235         # see if entry is a flag
 236         if (/^:\w+$/) {
 237             $search     = 0 if lc eq ':nosearch';
 238             $search     = 1 if lc eq ':search';
 239             warn "Ignoring unknown flag '$thislib'\n"
 240                 if $verbose and !/^:(no)?(search|default)$/i;
 241             next;
 242         }
 243
 244         # if searching is disabled, do compiler-specific translations
 245         unless ($search) {
 246             s/^-l(.+)$/$1.lib/ unless $GC;
 247             s/^-L/-libpath:/ if $VC;
 248             push(@extralibs, $_);
 249             $found++;
 250             next;
 251         }
 252
 253         # handle possible linker path arguments
 254         if (s/^-L// and not -d) {
 255             warn "$thislib ignored, directory does not exist\n"
 256                 if $verbose;
 257             next;
 258         }
 259         elsif (-d) {
 260             unless ($self->file_name_is_absolute($_)) {
 261               warn "Warning: '$thislib' changed to '-L$pwd/$_'\n";
 262               $_ = $self->catdir($pwd,$_);
 263             }
 264             push(@searchpath, $_);
 265             next;
 266         }
 267
 268         # handle possible library arguments
 269         if (s/^-l// and $GC and !/^lib/i) {
 270             $_ = "lib$_";
 271         }
 272         $_ .= $libext if !/\Q$libext\E$/i;
 273
 274         my $secondpass = 0;
 275     LOOKAGAIN:
 276
 277         # look for the file itself
 278         if (-f) {
 279             warn "'$thislib' found as '$_'\n" if $verbose;
 280             $found++;
 281             push(@extralibs, $_);
 282             next;
 283         }
 284
 285         my $found_lib = 0;
 286         foreach $thispth (@searchpath, @libpath){
 287             unless (-f ($fullname="$thispth\\$_")) {
 288                 warn "'$thislib' not found as '$fullname'\n" if $verbose;
 289                 next;
 290             }
 291             warn "'$thislib' found as '$fullname'\n" if $verbose;
 292             $found++;
 293             $found_lib++;
 294             push(@extralibs, $fullname);
 295             last;
 296         }
 297
 298         # do another pass with (or without) leading 'lib' if they used -l
 299         if (!$found_lib and $thislib =~ /^-l/ and !$secondpass++) {
 300             if ($GC) {
 301                 goto LOOKAGAIN if s/^lib//i;
 302             }
 303             elsif (!/^lib/i) {
 304                 $_ = "lib$_";
 305                 goto LOOKAGAIN;
 306             }
 307         }
 308
 309         # give up
 310         warn "Note (probably harmless): "
 311                      ."No library found for '$thislib'\n"
 312             unless $found_lib>0;
 313
 314     }
 315
 316     return ('','','','') unless $found;
 317
 318     # make sure paths with spaces are properly quoted
 319     @extralibs = map { (/\s/ && !/^".*"$/) ? qq["$_"] : $_ } @extralibs;
 320     $lib = join(' ',@extralibs);
 321
 322     # normalize back to backward slashes (to help braindead tools)
 323     # XXX this may break equally braindead GNU tools that don't understand
 324     # backslashes, either.  Seems like one can't win here.  Cursed be CP/M.
 325     $lib =~ s,/,\\,g;
 326
 327     warn "Result: $lib\n" if $verbose;
 328     wantarray ? ($lib, '', $lib, '') : $lib;
 329 }
 330
 331
 332 sub _vms_ext {
 333   my($self, $potential_libs,$verbose) = @_;
 334   my(@crtls,$crtlstr);
 335   my($dbgqual) = $self->{OPTIMIZE} || $Config{'optimize'} ||
 336                  $self->{CCFLAS}   || $Config{'ccflags'};
 337   @crtls = ( ($dbgqual =~ m-/Debug-i ? $Config{'dbgprefix'} : '')
 338               . 'PerlShr/Share' );
 339   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libs'});
 340   push(@crtls, grep { not /\(/ } split /\s+/, $Config{'libc'});
 341   # In general, we pass through the basic libraries from %Config unchanged.
 342   # The one exception is that if we're building in the Perl source tree, and
 343   # a library spec could be resolved via a logical name, we go to some trouble
 344   # to insure that the copy in the local tree is used, rather than one to
 345   # which a system-wide logical may point.
 346   if ($self->{PERL_SRC}) {
 347     my($lib,$locspec,$type);
 348     foreach $lib (@crtls) {
 349       if (($locspec,$type) = $lib =~ m-^([\w$\-]+)(/\w+)?- and $locspec =~ /perl/i) {
 350         if    (lc $type eq '/share')   { $locspec .= $Config{'exe_ext'}; }
 351         elsif (lc $type eq '/library') { $locspec .= $Config{'lib_ext'}; }
 352         else                           { $locspec .= $Config{'obj_ext'}; }
 353         $locspec = $self->catfile($self->{PERL_SRC},$locspec);
 354         $lib = "$locspec$type" if -e $locspec;
 355       }
 356     }
 357   }
 358   $crtlstr = @crtls ? join(' ',@crtls) : '';
 359
 360   unless ($potential_libs) {
 361     warn "Result:\n\tEXTRALIBS: \n\tLDLOADLIBS: $crtlstr\n" if $verbose;
 362     return ('', '', $crtlstr, '');
 363   }
 364
 365   my(@dirs,@libs,$dir,$lib,%found,@fndlibs,$ldlib);
 366   my $cwd = cwd();
 367   my($so,$lib_ext,$obj_ext) = @Config{'so','lib_ext','obj_ext'};
 368   # List of common Unix library names and there VMS equivalents
 369   # (VMS equivalent of '' indicates that the library is automatially
 370   # searched by the linker, and should be skipped here.)
 371   my %libmap = ( 'm' => '', 'f77' => '', 'F77' => '', 'V77' => '', 'c' => '',
 372                  'malloc' => '', 'crypt' => '', 'resolv' => '', 'c_s' => '',
 373                  'socket' => '', 'X11' => 'DECW$XLIBSHR',
 374                  'Xt' => 'DECW$XTSHR', 'Xm' => 'DECW$XMLIBSHR',
 375                  'Xmu' => 'DECW$XMULIBSHR');
 376   if ($Config{'vms_cc_type'} ne 'decc') { $libmap{'curses'} = 'VAXCCURSE'; }
 377
 378   warn "Potential libraries are '$potential_libs'\n" if $verbose;
 379
 380   # First, sort out directories and library names in the input
 381   foreach $lib (split ' ',$potential_libs) {
 382     push(@dirs,$1),   next if $lib =~ /^-L(.*)/;
 383     push(@dirs,$lib), next if $lib =~ /[:>\]]$/;
 384     push(@dirs,$lib), next if -d $lib;
 385     push(@libs,$1),   next if $lib =~ /^-l(.*)/;
 386     push(@libs,$lib);
 387   }
 388   push(@dirs,split(' ',$Config{'libpth'}));
 389
 390   # Now make sure we've got VMS-syntax absolute directory specs
 391   # (We don't, however, check whether someone's hidden a relative
 392   # path in a logical name.)
 393   foreach $dir (@dirs) {
 394     unless (-d $dir) {
 395       warn "Skipping nonexistent Directory $dir\n" if $verbose > 1;
 396       $dir = '';
 397       next;
 398     }
 399     warn "Resolving directory $dir\n" if $verbose;
 400     if ($self->file_name_is_absolute($dir)) { $dir = $self->fixpath($dir,1); }
 401     else                                    { $dir = $self->catdir($cwd,$dir); }
 402   }
 403   @dirs = grep { length($_) } @dirs;
 404   unshift(@dirs,''); # Check each $lib without additions first
 405
 406   LIB: foreach $lib (@libs) {
 407     if (exists $libmap{$lib}) {
 408       next unless length $libmap{$lib};
 409       $lib = $libmap{$lib};
 410     }
 411
 412     my(@variants,$variant,$name,$test,$cand);
 413     my($ctype) = '';
 414
 415     # If we don't have a file type, consider it a possibly abbreviated name and
 416     # check for common variants.  We try these first to grab libraries before
 417     # a like-named executable image (e.g. -lperl resolves to perlshr.exe
 418     # before perl.exe).
 419     if ($lib !~ /\.[^:>\]]*$/) {
 420       push(@variants,"${lib}shr","${lib}rtl","${lib}lib");
 421       push(@variants,"lib$lib") if $lib !~ /[:>\]]/;
 422     }
 423     push(@variants,$lib);
 424     warn "Looking for $lib\n" if $verbose;
 425     foreach $variant (@variants) {
 426       foreach $dir (@dirs) {
 427         my($type);
 428
 429         $name = "$dir$variant";
 430         warn "\tChecking $name\n" if $verbose > 2;
 431         if (-f ($test = VMS::Filespec::rmsexpand($name))) {
 432           # It's got its own suffix, so we'll have to figure out the type
 433           if    ($test =~ /(?:$so|exe)$/i)      { $type = 'SHR'; }
 434           elsif ($test =~ /(?:$lib_ext|olb)$/i) { $type = 'OLB'; }
 435           elsif ($test =~ /(?:$obj_ext|obj)$/i) {
 436             warn "Note (probably harmless): "
 437                          ."Plain object file $test found in library list\n";
 438             $type = 'OBJ';
 439           }
 440           else {
 441             warn "Note (probably harmless): "
 442                          ."Unknown library type for $test; assuming shared\n";
 443             $type = 'SHR';
 444           }
 445         }
 446         elsif (-f ($test = VMS::Filespec::rmsexpand($name,$so))      or
 447                -f ($test = VMS::Filespec::rmsexpand($name,'.exe')))     {
 448           $type = 'SHR';
 449           $name = $test unless $test =~ /exe;?\d*$/i;
 450         }
 451         elsif (not length($ctype) and  # If we've got a lib already, don't bother
 452                ( -f ($test = VMS::Filespec::rmsexpand($name,$lib_ext)) or
 453                  -f ($test = VMS::Filespec::rmsexpand($name,'.olb'))))  {
 454           $type = 'OLB';
 455           $name = $test unless $test =~ /olb;?\d*$/i;
 456         }
 457         elsif (not length($ctype) and  # If we've got a lib already, don't bother
 458                ( -f ($test = VMS::Filespec::rmsexpand($name,$obj_ext)) or
 459                  -f ($test = VMS::Filespec::rmsexpand($name,'.obj'))))  {
 460           warn "Note (probably harmless): "
 461                        ."Plain object file $test found in library list\n";
 462           $type = 'OBJ';
 463           $name = $test unless $test =~ /obj;?\d*$/i;
 464         }
 465         if (defined $type) {
 466           $ctype = $type; $cand = $name;
 467           last if $ctype eq 'SHR';
 468         }
 469       }
 470       if ($ctype) {
 471         # This has to precede any other CRTLs, so just make it first
 472         if ($cand eq 'VAXCCURSE') { unshift @{$found{$ctype}}, $cand; }
 473         else                      { push    @{$found{$ctype}}, $cand; }
 474         warn "\tFound as $cand (really $test), type $ctype\n" if $verbose > 1;
 475         next LIB;
 476       }
 477     }
 478     warn "Note (probably harmless): "
 479                  ."No library found for $lib\n";
 480   }
 481
 482   push @fndlibs, @{$found{OBJ}}                      if exists $found{OBJ};
 483   push @fndlibs, map { "$_/Library" } @{$found{OLB}} if exists $found{OLB};
 484   push @fndlibs, map { "$_/Share"   } @{$found{SHR}} if exists $found{SHR};
 485   $lib = join(' ',@fndlibs);
 486
 487   $ldlib = $crtlstr ? "$lib $crtlstr" : $lib;
 488   warn "Result:\n\tEXTRALIBS: $lib\n\tLDLOADLIBS: $ldlib\n" if $verbose;
 489   wantarray ? ($lib, '', $ldlib, '') : $lib;
 490 }
 491
 492 1;
 493
 494 __END__
 495
 496 =head1 NAME
 497
 498 ExtUtils::Liblist - determine libraries to use and how to use them
 499
 500 =head1 SYNOPSIS
 501
 502 C<require ExtUtils::Liblist;>
 503
 504 C<ExtUtils::Liblist::ext($self, $potential_libs, $verbose);>
 505
 506 =head1 DESCRIPTION
 507
 508 This utility takes a list of libraries in the form C<-llib1 -llib2
 509 -llib3> and prints out lines suitable for inclusion in an extension
 510 Makefile.  Extra library paths may be included with the form
 511 C<-L/another/path> this will affect the searches for all subsequent
 512 libraries.
 513
 514 It returns an array of four scalar values: EXTRALIBS, BSLOADLIBS,
 515 LDLOADLIBS, and LD_RUN_PATH.  Some of these don't mean anything
 516 on VMS and Win32.  See the details about those platform specifics
 517 below.
 518
 519 Dependent libraries can be linked in one of three ways:
 520
 521 =over 2
 522
 523 =item * For static extensions
 524
 525 by the ld command when the perl binary is linked with the extension
 526 library. See EXTRALIBS below.
 527
 528 =item * For dynamic extensions
 529
 530 by the ld command when the shared object is built/linked. See
 531 LDLOADLIBS below.
 532
 533 =item * For dynamic extensions
 534
 535 by the DynaLoader when the shared object is loaded. See BSLOADLIBS
 536 below.
 537
 538 =back
 539
 540 =head2 EXTRALIBS
 541
 542 List of libraries that need to be linked with when linking a perl
 543 binary which includes this extension. Only those libraries that
 544 actually exist are included.  These are written to a file and used
 545 when linking perl.
 546
 547 =head2 LDLOADLIBS and LD_RUN_PATH
 548
 549 List of those libraries which can or must be linked into the shared
 550 library when created using ld. These may be static or dynamic
 551 libraries.  LD_RUN_PATH is a colon separated list of the directories
 552 in LDLOADLIBS. It is passed as an environment variable to the process
 553 that links the shared library.
 554
 555 =head2 BSLOADLIBS
 556
 557 List of those libraries that are needed but can be linked in
 558 dynamically at run time on this platform.  SunOS/Solaris does not need
 559 this because ld records the information (from LDLOADLIBS) into the
 560 object file.  This list is used to create a .bs (bootstrap) file.
 561
 562 =head1 PORTABILITY
 563
 564 This module deals with a lot of system dependencies and has quite a
 565 few architecture specific C<if>s in the code.
 566
 567 =head2 VMS implementation
 568
 569 The version of ext() which is executed under VMS differs from the
 570 Unix-OS/2 version in several respects:
 571
 572 =over 2
 573
 574 =item *
 575
 576 Input library and path specifications are accepted with or without the
 577 C<-l> and C<-L> prefixes used by Unix linkers.  If neither prefix is
 578 present, a token is considered a directory to search if it is in fact
 579 a directory, and a library to search for otherwise.  Authors who wish
 580 their extensions to be portable to Unix or OS/2 should use the Unix
 581 prefixes, since the Unix-OS/2 version of ext() requires them.
 582
 583 =item *
 584
 585 Wherever possible, shareable images are preferred to object libraries,
 586 and object libraries to plain object files.  In accordance with VMS
 587 naming conventions, ext() looks for files named I<lib>shr and I<lib>rtl;
 588 it also looks for I<lib>lib and libI<lib> to accommodate Unix conventions
 589 used in some ported software.
 590
 591 =item *
 592
 593 For each library that is found, an appropriate directive for a linker options
 594 file is generated.  The return values are space-separated strings of
 595 these directives, rather than elements used on the linker command line.
 596
 597 =item *
 598
 599 LDLOADLIBS contains both the libraries found based on C<$potential_libs> and
 600 the CRTLs, if any, specified in Config.pm.  EXTRALIBS contains just those
 601 libraries found based on C<$potential_libs>.  BSLOADLIBS and LD_RUN_PATH
 602 are always empty.
 603
 604 =back
 605
 606 In addition, an attempt is made to recognize several common Unix library
 607 names, and filter them out or convert them to their VMS equivalents, as
 608 appropriate.
 609
 610 In general, the VMS version of ext() should properly handle input from
 611 extensions originally designed for a Unix or VMS environment.  If you
 612 encounter problems, or discover cases where the search could be improved,
 613 please let us know.
 614
 615 =head2 Win32 implementation
 616
 617 The version of ext() which is executed under Win32 differs from the
 618 Unix-OS/2 version in several respects:
 619
 620 =over 2
 621
 622 =item *
 623
 624 If C<$potential_libs> is empty, the return value will be empty.
 625 Otherwise, the libraries specified by C<$Config{libs}> (see Config.pm)
 626 will be appended to the list of C<$potential_libs>.  The libraries
 627 will be searched for in the directories specified in C<$potential_libs>,
 628 C<$Config{libpth}>, and in C<$Config{installarchlib}/CORE>.
 629 For each library that is found,  a space-separated list of fully qualified
 630 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> prefixes 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 C<-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