NAME

       lib::relative - Add paths relative to the current file to @INC

SYNOPSIS

         # Path is relative to this file, not current working directory
         use lib::relative 'path/to/lib';
         use lib::relative '../../lib';

         # Add two lib paths, as in lib.pm
         use lib::relative 'foo', 'bar';

         # Absolute paths are passed through unchanged
         use lib::relative 'foo/baz', '/path/to/lib';

         # Equivalent code using core modules
         use Cwd ();
         use File::Basename ();
         use File::Spec ();
         use lib File::Spec->catdir(File::Basename::dirname(Cwd::abs_path __FILE__), 'path/to/lib');

DESCRIPTION

       Adding a path to @INC to load modules from a local directory may seem simple, but has a
       few common pitfalls to be aware of. Directly adding a relative path to @INC means that any
       later code that changes the current working directory will change where modules are loaded
       from. This applies to the "." path that used to be in @INC by default until perl 5.26.0,
       or a relative path added in code like "use lib 'path/to/lib'", and may be a vulnerability
       if such a location is not supposed to be writable. Additionally, the commonly used FindBin
       module relies on interpreter state and the path to the original script invoked by the perl
       interpreter, sometimes requiring workarounds in uncommon cases like generated or embedded
       code. This module proposes a more straightforward method: take a path relative to the
       current file, absolutize it, and add it to @INC.

       If this module is already available to be loaded, it can be used as with lib.pm, passing
       relative paths, which will be absolutized relative to the current file then passed on to
       lib. Multiple arguments will be separately absolutized, and absolute paths will be passed
       on unchanged.

       For cases where this module cannot be loaded beforehand, the last section of the
       "SYNOPSIS" can be copy-pasted into a file to perform the same task.

CAVEATS

       Due to "__FILE__" possibly being a path relative to the current working directory, be sure
       to use "lib::relative" or the equivalent code from "SYNOPSIS" as early as possible in the
       file. If a "chdir" occurs before this code, it will add the incorrect directory path.

       All file paths are expected to be in a format appropriate to the current operating system,
       e.g. "..\\foo\\bar" on Windows. "catdir" in File::Spec can be used to form directory paths
       portably.

BUGS

       Report any issues on the public bugtracker.

AUTHOR

       Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2017 by Dan Book.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

SEE ALSO

       lib, FindBin, Dir::Self