NAME
FindBin::Bin - Absolute path to the executable's directory, with two normalization strategies for paths containing .. segments.
SYNOPSIS
# Exports two variables (and matching constant subs) for the
# directory containing the running program, plus two utilities.
# $Bin defaults to the physical path (abspath); pass 'noabspath'
# to get the logical path. This matches FindBin::libs behavior.
use FindBin::Bin
qw(
$Bin # physical path by default; logical with 'noabspath' (see below)
Bin # constant sub returning same value as $Bin
$Bin_l # logical path via canon_dir (stack-based '..' removal, like pwd -L)
Bin_l # constant sub returning $Bin_l
$Bin_p # physical path via Cwd::abs_path (resolves symlinks, like pwd -P)
Bin_p # constant sub returning $Bin_p
pwd # absolute CWD, symlinks preserved (like "pwd -L")
canon_dir # remove '..' and '.' without touching the filesystem
);
# $Bin defaults to the physical path (same as $Bin_p, abspath).
# Pass 'noabspath' to get the logical path (same as $Bin_l):
use FindBin::Bin qw( $Bin ); # $Bin == $Bin_p (physical, default)
use FindBin::Bin qw( $Bin noabspath ); # $Bin == $Bin_l (logical)
use FindBin::Bin qw( $Bin abspath ); # $Bin == $Bin_p (physical, explicit)
# For paths with no symlinks, all three variables are identical:
say $Bin; # /home/jowbloe/project/bin
say $Bin_l; # /home/jowbloe/project/bin (canon_dir, logical)
say $Bin_p; # /home/jowbloe/project/bin (abs_path, physical)
# They differ when the path to the program ($0) includes any
# symbolic links.
# If /home/jowbloe is a symlink to /real/home/jowbloe:
say $Bin_l; # /home/jowbloe/project/bin (symlinks preserved)
say $Bin_p; # /real/home/jowbloe/project/bin (symlinks resolved)
# Interactive invocations (perl -e, perl -E, perl -, debugger) and
# input via a filehandle (perl /dev/stdin, perl <( ... )):
# $Bin_l = pwd() -- CWD as returned by pwd()
# $Bin_p = abs_path(pwd()) -- CWD with symlinks resolved
perl -MFindBin::Bin=Bin -e 'say Bin';
perl - < ../../foo/bar/bim;
# Named programs: directory component of $0, with pwd() prepended
# when $0 is relative. All variables are absolute at program startup.
use FindBin::Bin qw( pwd );
my $cwd = pwd; # same as "pwd -L" on *NIX
use FindBin::Bin qw( canon_dir );
my $path = canon_dir '/foo/bar/../bletch/./../blort';
# => '/foo/blort'
my $clamped = canon_dir '/foo/bar/../../../../../../../';
# => '/' (cannot '..' past root)
DESCRIPTION
This module computes three absolute-path forms of the directory that contains the running program ($0) and exports them at compile time in a BEGIN block.
$Bin and Bin()
$Bin is a configurable alias. By default it equals $Bin_p (the physical path, symlinks resolved). Passing 'noabspath' in the import list makes $Bin equal $Bin_l (the logical path, symlinks preserved) in the calling package:
use FindBin::Bin qw( $Bin ); # $Bin == $Bin_p (physical, default)
use FindBin::Bin qw( $Bin noabspath ); # $Bin == $Bin_l (logical)
use FindBin::Bin qw( $Bin abspath ); # $Bin == $Bin_p (physical, explicit)
Bin() follows the same logic: it is aliased to Bin_p() or Bin_l() depending on the noabspath flag.
This behavior matches FindBin::libs, which also defaults to the physical path and accepts noabspath to select the logical path.
The first argument to import is the package name FindBin::Bin, not an object instance. These modules provide no OO interface.
$Bin_l and Bin_l()
$Bin_l ("logical", like pwd -L) is the directory of $0 as given, with pwd() prepended if $0 is relative, cleaned up via canon_dir(): a stack algorithm that removes all .. and . segments without touching the filesystem. Symbolic links in the path are preserved; if $0 is itself a symlink, $Bin_l is the directory containing the symlink. Because pwd() uses $ENV{PWD} when it is valid, a relative $0 keeps the symlinks in the working directory as well.
$Bin_p and Bin_p()
$Bin_p ("physical", like pwd -P) is the directory of Cwd::abs_path( $0 ): the physical directory of the executable file, with all symbolic links resolved. If $0 is itself a symlink, $Bin_p is the directory containing the file it points to.
Symlinks
$Bin_l preserves directory symlinks in the path (logical, like pwd -L). $Bin_p resolves them to the real on-disk location (physical, like pwd -P). They are identical when no symlinks appear in the path to $0, including $0 itself:
# $0 = /home/user/bin/script, a symlink to /work/app/bin/script
$Bin_l = /home/user/bin # directory of the symlink
$Bin_p = /work/app/bin # directory of the executable file
Bind mounts, on *NIX systems that support them, can also give a different $Bin_l. If $ENV{PWD} names the working directory via one mount point and the process entered it via another, both have the same device and inode, so pwd() accepts $ENV{PWD}. With a relative $0, $Bin_l then uses the $ENV{PWD} mount point while $Bin_p uses the one returned by abs_path, though neither path contains a symlink.
Example: two lib trees, one symlink
Consider a sandbox layout where /home/user/app is a directory symlink pointing to the real project under /work/projects/app:
/home/user/ # logical subtree
+-- lib/
| \-- UserLib.pm # visible only via $Bin_l
\-- app -> /work/projects/app # directory symlink
/work/projects/ # physical subtree
+-- lib/
| \-- WorkLib.pm # visible only via $Bin_p
\-- app/
\-- bin/
\-- script # $0 -- the running program
When script is invoked via the symlink path (/home/user/app/bin/script):
$Bin_l = /home/user/app/bin # symlink path preserved
$Bin_p = /work/projects/app/bin # symlink resolved
FindBin::libs (and any other code that walks up from $Bin) finds different lib/ directories depending on which variable it uses as the starting point.
Using $Bin_l (noabspath):
walk: /home/user/app/bin -> /home/user/app -> /home/user
lib found: /home/user/lib
use lib '/home/user/lib' # loads UserLib.pm
Using $Bin_p (abspath, the default):
walk: /work/projects/app/bin -> /work/projects/app -> /work/projects
lib found: /work/projects/lib
use lib '/work/projects/lib' # loads WorkLib.pm
This is the "regression testing via symlinks" pattern: place a directory symlink to the program's bin inside a test sandbox that has its own lib/ tree. Toggle between the sandbox libraries (logical) and the source-tree libraries (physical) with the abspath setting in FindBin::libs, or by choosing which variable to use directly.
The default $Bin equals $Bin_p unless the caller passes 'noabspath' at import time (see "$Bin and Bin()").
Resolving the working directory
The $Bin* variables and Bin*() subs are computed once, when FindBin::Bin is first loaded: at compile time of the first use FindBin::Bin or use FindBin::libs. When $0 is relative or an interactive invocation they are based on the value of pwd() at that time; an absolute $0 does not use pwd().
If FindBin::libs or FindBin::Bin is used before any chdir, they reflect the working directory at startup: a relative $0 is resolved against the original pwd(), giving the correct absolute path. A later chdir does not change them. Using FindBin::libs before other modules avoids the problems below.
A chdir made before FindBin::Bin is first loaded, e.g., by a module used earlier, affects them:
Builtin
chdirDoes not update
$ENV{PWD}.pwd()finds the stale$PWD, warns, and usesCwd::getcwd(), so$Bin_ldoes not preserve symlinks.Cwd::chdirUpdates
$ENV{PWD}.pwd()uses it without a warning.
In either case, if the working directory is not restored before FindBin::Bin is loaded, a relative $0 is resolved against the new working directory, and $Bin_l and $Bin_p are wrong.
Interactive invocations
When $0 is -e, -, or interactive (one-liner, stdin, or debugger), or a path under /dev/ (input via a filehandle, e.g., perl /dev/stdin or /dev/fd/N from bash process substitution), the directory is taken from pwd():
$Bin_l = pwd()
$Bin_p = Cwd::abs_path( pwd() ) # resolves symlinks in CWD
Named program files
When $0 holds a file path:
$Bin_l = catpath( $vol, canon_dir( $dir ), '' )
$Bin_p = directory of abs_path( $0 )
where $vol and $dir are the volume and directory of $0 as given; canon_dir() prepends pwd() to a relative $dir. $Bin_l keeps symlinks, including a symlinked $0; $Bin_p resolves them, following a symlinked $0 to the executable file.
All variables are defined as read-only ref-to-constant scalars and constant subs; they do not change after the BEGIN block runs.
pwd()
Returns the working directory determined at runtime, the same value as "pwd -L" -- an absolute path with symbolic links left as-is. On *NIX and Cygwin it validates $ENV{PWD} against the inode of '.' and falls back to Cwd::getcwd() (which resolves symlinks) only when they disagree. On VMS it uses $ENV{DEFAULT} if that is defined, otherwise Cwd::getcwd(); on MSWin32 it uses Cwd::getcwd().
If $ENV{PWD} is set but stale -- not an absolute path, a path that does not exist, or not the same device and inode as '.' -- pwd() warns:
Mismatched working directory: '<$ENV{PWD}>' is stale,
using '<getcwd>', this resolves symbolic links.
and returns Cwd::getcwd(), so symlinks in the working directory are not preserved. The usual cause is a builtin chdir, which does not update $ENV{PWD}; Cwd::chdir does. No warning is issued when $ENV{PWD} is unset.
If the working directory cannot be resolved, e.g., it has been removed, getcwd returns undef and pwd() dies:
Unresolvable working directory: getcwd() returned undef (<$!>)
This is checked first, on all platforms, before $ENV{PWD} or $ENV{DEFAULT} is examined. abs_path cannot detect it, since it returns a missing last path component unchanged.
The result is cached on the first call to pwd(): later calls return the same value, even after a chdir. The first call is not necessarily at program startup. Loading FindBin::Bin calls pwd() only when $0 is relative or an interactive invocation (-e, -, interactive, /dev/...); otherwise the first call is the caller's, and reflects any chdir made before it.
canon_dir()
Accepts an absolute or relative path and returns an absolute path with all . and .. components removed via a stack algorithm. Symlinks are not consulted. A relative input has pwd() prepended.
canon_dir '/foo/bar/../bim/../../bletch';
# => '/bletch' (.. backs off bar, then bim, then foo)
canon_dir '/foo/bar/../../../../../../../';
# => '/' (cannot go above root)