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