view release on metacpan or  search on metacpan

version/v5.40/lib/FindBin/libs.pm  view on Meta::CPAN

to check the code.

=back

=head1 Notes

=head2 Alternatives

FindBin::libs was developed to avoid pitfalls with
the items listed below. As of FindBin::libs-1.20,
this is also mutli-platform, where other techniques
may be limited to *NIX or at least less portable.

=over 4

=item 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.

=item 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.

=item 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.

=back

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

In order to accmodate a wider range of filesystems,
the code has been re-written to use File::Spec for
all directory and volume manglement.

=head1 See Also

=over 4

=item File::Spec

This is used for portability in dis- and re-assembling
directory paths based on $FindBin::Bin.

=item Older code.

FindBin::libs_5_8.pm is installed if $^V indicates
that the running perl is prior to v5.10. See the
./versions dir in the distro for list of Perl version
increments.

=back

=head1 BUGS

=over 4

=item

In order to avoid including junk, FindBin::libs
uses '-d' to test the items before including
them on the library list.

abs_path causes too many issues where symlinks
are useful, at this point I've given up trying
to make it work. This may leave multiple paths
to the same location in multiple points of the
directory stack. So be it.

This also means I've had to replace FindBin as
the source of the execution directory. I've used
a mirror of the Raku code for FindBin and
FindBin::Parent here as seprate modules. These
depend only on File::Spec and do not use abs_path.

=item

File::Spec 3.16 and prior have a bug in VMS of