General Use

Options controll whether the lib's found are exported into the caller's space, exported to PERL5LIB, or printed. Exporting or setting perl5lib will turn off the default of "use lib" so that:

    use FindBin::libs qw( export );
    use FindBin::libs qw( p5lib  );

are equivalent to

    use FindBin::libs qw( export nouse );
    use FindBin::libs qw( p5lib  nouse );

Combining export with use or p5lib may be useful, p5lib and use are probably not all that useful together.

Alternate directory name: 'base'

The basename searched for can be changed via 'base=name' so that

    use FindBin::libs qw( base=altlib );

will search for directories named "altlib" and "use lib" them.

Exporting a variable: "export", "scalar", "append"

"export"

This installs the results of locating directories into the caller's space. Without any argument, export pushes out a variable named after the located [sub]dir; an argument can be supplied to give the variable name. Without the "scalar" option, the exported variable will be an array in increasing order of "distance" (i.e., "up" the file tree); with the "scalar" option only the first (i.e., "nearest") path is exported.

If "export" is given then "nouse" is assumed; using both leaves the variable exported and its contents handed to "use lib".

For example:

    use FindBin::libs qw( export );
    

will find "lib" directories and export @lib with the list of directories found.

    use FindBin::libs qw( export=mylibs );
    

will find "lib" directories and export them as "@mylibs" to the caller.

If "export" only is given then the "use" option defaults to false. So:

    use FindBin::libs qw( export );
    use FindBin::libs qw( export nouse );
    

are equivalent. This is mainly for use when looking for data directories with the "base=" argument.

If base is used with export the default array name is the base directory value:

    use FindBin::libs qw( export base=meta );
    

exports @meta while

    use FindBin::libs qw( export=metadirs base=meta );
    

exports @metadirs as a list of paths ending in "/meta".

The use and export switches are not exclusive:

    use FindBin::libs qw( use export=mylibs );
    

will locate "lib" directories, use lib them, and export @mylibs into the caller's package.

"scalar"

Only searches for the first directory, which is exported (or overwritten) as a scalar rather than array. For example, if a project directory has ./bin and ./etc dir's then #! code in bin with

    use FindBin::libs qw( export scalar base=etc );
    

will have an $etc variable with the absolute path to ./bin/../etc. For configuration varibles this is usually what you want and allows for "$etc/Foo.conf" rather than "$etc[0]/Foo.conf".

"append"

Sometimes it's simpler to accumulate multiple searches into a single array. Say for ./etc dir's in collection of standard locations.

In that case:

    use FindBin::libs qw( export=etc base=foo subdir=etc );
    use FindBin::libs qw( export=etc base=bar subdir=etc append );
    

produces something like

    (
        /path/to/foo/etc
        /path/to/bar/etc
    )
    

without append @etc will have only ./bar/etc since the array would be overwritten with each call to FB::l::import.

Subdirectories

    use FindBin::libs;
    use FindBin::libs qw( subdir=perl5 subonly );

    use FindBin::libs qw( export base=config subonly=mypackage );

    ./proj/Foo/etc
    ./proj/etc

    use FindBin::libs qw( export subdir=etc subonly )

    use List::Util qw( first );

    my $path = first { -e "$_/Global.config" } @etc;

Setting PERL5LIB: p5lib

For cases where the environment is more useful for setting up library paths "p5lib" can be used to preload this variable. This is mainly useful for automatically including directories outside of the parent tree of $FindBin::bin.

For example, using:

    $ export PERL5LIB="/usr/local/foo:/usr/local/bar";

    $ myprog;

or simply

    $ PERL5LIB="/usr/local/lib/foo:/usr/lib/bar" myprog;

(depending on your shell) with #! code including:

    use FindBin::libs qw( p5lib );

will not "use lib" any dir's found but will update PERL5LIB to something like:

    /home/me/sandbox/branches/lib:/usr/local/lib/foo:/usr/lib/bar

This can make controlling the paths used simpler and avoid the use of symlinks for some testing (see examples below).

Skipping directories

    use FindBin::libs qw( ignore=/skip/this,/and/this/also );

will replace the standard list and thus skip "/skip/this/lib" and "/and/this/also/lib". It will search "/lib" and "/usr/lib" since the argument ignore list replaces the original one.

Homegrown Library Management

    use lib qw( /usr/local/projectX ... )

code at the top of each #! file that has to be updated by hand for each new project.

To get away from this you'll often see relative paths for the lib's, which require running the code from one specific place. All this does is push the hard-coding into cron, shell wrappers, and begin blocks.

With FindBin::libs you need suffer no more.

Automatically finding libraries in and above the executable means you can put your modules into cvs/svn and check them out with the project, have multiple copies shared by developers, or easily move a module up the directory tree in a testbed to regression test the module with existing code. All without having to modify a single line of code.

Code-speicfic modules.

Say your sandbox is in ./sandbox and you are currently working in ./sandbox/projects/package/bin on a perl executable. You may have some number of modules that are specific -- or customized -- for this pacakge, share some modules within the project, and may want to use company-wide modules that are managed out of ./sandbox in development. All of this lives under a ./qc tree on the test boxes and under ./production on production servers.

For simplicity, say that your sandbox lives in your home direcotry, /home/jowbloe, as a directory or a symlink.

If your #! uses FindBin::libs in it then it will effectively

    use lib
    qw(
        /home/jowbloe/sandbox/lib
        /home/jowbloe/sandbox/project/lib
        /home/jowbloe/sandbox/project/package/lib
    );
    

if you run /home/jowbloe/sandbox/project/package/bin/foobar. This will happen the same way if you use a relative or absolute path, perl -d the thing, or if any of the lib directories are symlinks outside of your sandbox.

This means that the most specific module directories ("closest" to your executable) will be picked up first.

If you have a version of Frobnicate.pm in your ./package/lib for modifications fine: you'll use it before the one in ./project or ./sandbox.

Using the "p5lib" argument can help in case where some of the code lives outside of the sandbox. To test a sandbox version of some other module:

    use FindBin::libs qw( p5lib );
    

and

    $ PERL5LIB=/other/sandbox/module foobar;
    

Regression Testing

Everntually, however, you'll need to regression test Frobnicate.pm with other modules.

Fine: move, copy, or symlink it into ./project/lib and you can merrily run ./project/*/bin/* with it and see if there are any problems. In fact, so can the nice folks in QC.

If you want to install and test a new module just prefix it into, say, ./sandbox/lib and all the code that has FindBin::libs will simply use it first.

Testing with Symlinks

$FindBin::Bin is relative to where an executable is started from. This allows a symlink to change the location of directories used by FindBin::libs. Full regression testing of an executable can be accomplished with a symlink:

    ./sandbox
        ./lib -> /homegrown/dir/lib
        ./lib/What/Ever.pm

        ./pre-change
            ./bin/foobar

        ./post-change
            ./lib/What/Ever.pm
            ./bin/foobar -> ../../pre-last-change/bin/foobar
    

Running foobar symlinked into the post-change directory will test it with whatever collection of modules is in the post-change directory. A large regression test on some collection of changed modules can be performed with a few symlinks into a sandbox area.

Managing Configuration and Meta-data Files

The "base" option alters FindBin::libs standard base directory. This allows for a heirarchical set of metadata directories:

    ./sandbox
        ./meta
        ./project/
            ./meta

        ./project/package
            ./bin
            ./meta
    

with

    use FindBin::libs qw( base=meta export );

    sub read_meta
    {
        my $base = shift;

        for my $dir ( @meta )
        {
            # open the first one and return
            ...
        }

        # caller gets back empty list if nothing was read.

        ()
    }
    

using "prove" with local modules.

Modules that are not intended for CPAN will not usually have a Makefile.PL or Build setup. This makes it harder to check the code via "make test". Instead of hacking a one-time Makefile, FindBin::libs can be used to locate modules in a "lib" directory adjacent to the "t: directory. The setup for this module would look like:

    ./t/01.t
    ./t/02.t
    ...

    ./lib/FindBin/libs.pm
    

since the *.t files use FindBin::libs they can locate the most recent version of code without it having to be copied into a ./blib directory (usually via make) before being processed. If the module did not have a Makefile this would allow:

    prove t/*.t;
    

to check the code.

Alternatives

PERL5LIBS

PERL5LIB can be used to accomplish the same directory lookups as FindBin::libs. The problem is PERL5LIB often contains absolte paths and does not automatically change depending on where tests are run. This can leave you modifying a file, changing directory to see if it works with some other code and testing an unmodified version of the code via PERL5LIB. FindBin::libs avoids this by using $FindBin::bin to reference where the code is running from.

The same is true of trying to use almost any environmental solution, with Perl's built in mechanism or one based on $ENV{ PWD } or qx( pwd ).

Aside: Combining an existing PERL5LIB for out-of-tree lookups with the "p5lib" option works well for most development situations.

use lib qw( ../../../../Lib );

This works, but how many dots do you need to get all the working lib's into a module or #! code? Class distrubuted among several levels subdirectories may have qw( ../../../lib ) vs. qw( ../../../../lib ) or various combinations of them. Validating these by hand (let alone correcting them) leaves me crosseyed after only a short session.

Anchor on a fixed lib directory.

Given a standard directory, it is possible to use something like:

    BEGIN
    {
        my ( $libdir ) = $0 =~ m{ ^( .+? )/SOMEDIR/ }x;

        eval "use lib qw( $libdir )";
    }
    

This looks for a standard location (e.g., /path/to/Mylib) in the executable path (or cwd) and uses that.

The main problem here is that if the anchor ever changes (e.g., when moving code between projects or relocating directories now that SVN supports it) the path often has to change in multiple files. The regex also may have to support multiple platforms, or be broken into more complicated File::Spec code that probably looks pretty much like what

    use FindBin::libs qw( base=Mylib )
    

does anyway.

FindBin::libs-1.2+ uses File::Spec

There is one thing that File::Spec does not handle, hoever, which is fully reolving absolute paths. That still has to be handled via abs_path, when it works.

The issue is that File::Spec::rel2abs and Cwd::abs_path work differently: abs_path only returns true for existing directories and resolves symlinks; rel2abs simply prepends cwd() to any non-absolute paths.

The difference for FinBin::libs is that including redundant directories can lead to unexpected results in what gets included; looking up the contents of heavily-symlinked paths is slow (and has some -- admittedly unlikely -- failures at runtime). So, abs_path() is the preferred way to find where the lib's really live after they are found looking up the tree. Using abs_path() also avoids problems where the same directory is included twice in a sandbox' tree via symlinks.

Due to previous complaints that abs_path did not work properly on all systems, the current version of FindBin::libs uses File::Spec to break apart and re-assemble directories, with abs_path used optinally. If "abs_path cwd" works then abs_path is used on the directory paths handed by File::Spec::catpath(); otherwise the paths are used as-is. This may leave users on systms with non-working abs_path() having extra copies of external library directories in @INC.

Another issue is that I've heard reports of some systems failing the '-d' test on symlinks, where '-e' would have succeded.