lib/FindBin.pm

   1 # FindBin.pm
   2 #
   3 # Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
   4 # This program is free software; you can redistribute it and/or modify it
   5 # under the same terms as Perl itself.
   6
   7 =head1 NAME
   8
   9 FindBin - Locate directory of original perl script
  10
  11 =head1 SYNOPSIS
  12
  13  use FindBin;
  14  use lib "$FindBin::Bin/../lib";
  15
  16  or
  17
  18  use FindBin qw($Bin);
  19  use lib "$Bin/../lib";
  20
  21 =head1 DESCRIPTION
  22
  23 Locates the full path to the script bin directory to allow the use
  24 of paths relative to the bin directory.
  25
  26 This allows a user to setup a directory tree for some software with
  27 directories E<lt>rootE<gt>/bin and E<lt>rootE<gt>/lib and then the above example will allow
  28 the use of modules in the lib directory without knowing where the software
  29 tree is installed.
  30
  31 If perl is invoked using the B<-e> option or the perl script is read from
  32 C<STDIN> then FindBin sets both C<$Bin> and C<$RealBin> to the current
  33 directory.
  34
  35 =head1 EXPORTABLE VARIABLES
  36
  37  $Bin         - path to bin directory from where script was invoked
  38  $Script      - basename of script from which perl was invoked
  39  $RealBin     - $Bin with all links resolved
  40  $RealScript  - $Script with all links resolved
  41
  42 =head1 KNOWN ISSUES
  43
  44 If there are two modules using C<FindBin> from different directories
  45 under the same interpreter, this won't work. Since C<FindBin> uses a
  46 C<BEGIN> block, it'll be executed only once, and only the first caller
  47 will get it right. This is a problem under mod_perl and other persistent
  48 Perl environments, where you shouldn't use this module. Which also means
  49 that you should avoid using C<FindBin> in modules that you plan to put
  50 on CPAN. To make sure that C<FindBin> will work is to call the C<again>
  51 function:
  52
  53   use FindBin;
  54   FindBin::again(); # or FindBin->again;
  55
  56 In former versions of FindBin there was no C<again> function. The
  57 workaround was to force the C<BEGIN> block to be executed again:
  58
  59   delete $INC{'FindBin.pm'};
  60   require FindBin;
  61
  62 =head1 KNOWN BUGS
  63
  64 If perl is invoked as
  65
  66    perl filename
  67
  68 and I<filename> does not have executable rights and a program called I<filename>
  69 exists in the users C<$ENV{PATH}> which satisfies both B<-x> and B<-T> then FindBin
  70 assumes that it was invoked via the C<$ENV{PATH}>.
  71
  72 Workaround is to invoke perl as
  73
  74  perl ./filename
  75
  76 =head1 AUTHORS
  77
  78 FindBin is supported as part of the core perl distribution. Please send bug
  79 reports to E<lt>F<perlbug@perl.org>E<gt> using the perlbug program included with perl.
  80
  81 Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
  82 Nick Ing-Simmons E<lt>F<nik@tiuk.ti.com>E<gt>
  83
  84 =head1 COPYRIGHT
  85
  86 Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
  87 This program is free software; you can redistribute it and/or modify it
  88 under the same terms as Perl itself.
  89
  90 =cut
  91
  92 package FindBin;
  93 use Carp;
  94 require 5.000;
  95 require Exporter;
  96 use Cwd qw(getcwd abs_path);
  97 use Config;
  98 use File::Basename;
  99 use File::Spec;
 100
 101 @EXPORT_OK = qw($Bin $Script $RealBin $RealScript $Dir $RealDir);
 102 %EXPORT_TAGS = (ALL => [qw($Bin $Script $RealBin $RealScript $Dir $RealDir)]);
 103 @ISA = qw(Exporter);
 104
 105 $VERSION = "1.44";
 106
 107 sub init
 108 {
 109  *Dir = \$Bin;
 110  *RealDir = \$RealBin;
 111
 112  if($0 eq '-e' || $0 eq '-')
 113   {
 114    # perl invoked with -e or script is on C<STDIN>
 115
 116    $Script = $RealScript = $0;
 117    $Bin    = $RealBin    = getcwd();
 118   }
 119  else
 120   {
 121    my $script = $0;
 122
 123    if ($^O eq 'VMS')
 124     {
 125      ($Bin,$Script) = VMS::Filespec::rmsexpand($0) =~ /(.*\])(.*)/s;
 126      ($RealBin,$RealScript) = ($Bin,$Script);
 127     }
 128    else
 129     {
 130      my $dosish = ($^O eq 'MSWin32' or $^O eq 'os2');
 131      unless(($script =~ m#/# || ($dosish && $script =~ m#\\#))
 132             && -f $script)
 133       {
 134        my $dir;
 135        foreach $dir (File::Spec->path)
 136         {
 137         my $scr = File::Spec->catfile($dir, $script);
 138         if(-r $scr && (!$dosish || -x _))
 139          {
 140           $script = $scr;
 141
 142           if (-f $0)
 143            {
 144             # $script has been found via PATH but perl could have
 145             # been invoked as 'perl file'. Do a dumb check to see
 146             # if $script is a perl program, if not then $script = $0
 147             #
 148             # well we actually only check that it is an ASCII file
 149             # we know its executable so it is probably a script
 150             # of some sort.
 151
 152             $script = $0 unless(-T $script);
 153            }
 154           last;
 155          }
 156        }
 157      }
 158
 159      croak("Cannot find current script '$0'") unless(-f $script);
 160
 161      # Ensure $script contains the complete path incase we C<chdir>
 162
 163      $script = File::Spec->catfile(getcwd(), $script)
 164        unless File::Spec->file_name_is_absolute($script);
 165
 166      ($Script,$Bin) = fileparse($script);
 167
 168      # Resolve $script if it is a link
 169      while(1)
 170       {
 171        my $linktext = readlink($script);
 172
 173        ($RealScript,$RealBin) = fileparse($script);
 174        last unless defined $linktext;
 175
 176        $script = (File::Spec->file_name_is_absolute($linktext))
 177                   ? $linktext
 178                   : File::Spec->catfile($RealBin, $linktext);
 179       }
 180
 181      # Get absolute paths to directories
 182      $Bin     = abs_path($Bin)     if($Bin);
 183      $RealBin = abs_path($RealBin) if($RealBin);
 184     }
 185   }
 186 }
 187
 188 BEGIN { init }
 189
 190 *again = \&init;
 191
 192 1; # Keep require happy
 193