lib::relative(3pm)

1lib::relative(3)      User Contributed Perl Documentation     lib::relative(3)
2
3
4

NAME

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

SYNOPSIS

9         # Path is relative to this file, not current working directory
10         use lib::relative 'path/to/lib';
11         use lib::relative '../../lib';
12
13         # Add two lib paths, as in lib.pm
14         use lib::relative 'foo', 'bar';
15
16         # Absolute paths are passed through unchanged
17         use lib::relative 'foo/baz', '/path/to/lib';
18
19         # Equivalent code using core modules
20         use File::Basename ();
21         use File::Spec ();
22         use lib File::Spec->catdir(File::Spec->rel2abs(File::Basename::dirname(__FILE__)), 'path/to/lib');
23

DESCRIPTION

25       Adding a path to @INC to load modules from a local directory may seem
26       simple, but has a few common pitfalls to be aware of. Directly adding a
27       relative path to @INC means that any later code that changes the
28       current working directory will change where modules are loaded from.
29       This applies to the "." path that used to be in @INC by default until
30       perl 5.26.0, or a relative path added in code like "use lib
31       'path/to/lib'", and may be a vulnerability if such a location is not
32       supposed to be writable. Additionally, the commonly used FindBin module
33       relies on interpreter state and the path to the original script invoked
34       by the perl interpreter, sometimes requiring workarounds in uncommon
35       cases like generated or embedded code. This module proposes a more
36       straightforward method: take a path relative to the current file,
37       absolutize it, and add it to @INC.
38
39       If this module is already available to be loaded, it can be used as
40       with lib.pm, passing relative paths, which will be absolutized relative
41       to the current file then passed on to lib. Multiple arguments will be
42       separately absolutized, and absolute paths will be passed on unchanged.
43
44       For cases where this module cannot be loaded beforehand, the last
45       section of the "SYNOPSIS" can be copy-pasted into a file to perform the
46       same task.
47

CAVEATS

49       Due to "__FILE__" possibly being a path relative to the current working
50       directory, be sure to use "lib::relative" or the equivalent code from
51       "SYNOPSIS" as early as possible in the file. If a "chdir" occurs before
52       this code, it will add the incorrect directory path.
53
54       All file paths are expected to be in a format appropriate to the
55       current operating system, e.g. "..\\foo\\bar" on Windows. "catdir" in
56       File::Spec can be used to form directory paths portably.
57

BUGS

59       Report any issues on the public bugtracker.
60

AUTHOR

62       Dan Book <dbook@cpan.org>
63

COPYRIGHT AND LICENSE

65       This software is Copyright (c) 2017 by Dan Book.
66
67       This is free software, licensed under:
68
69         The Artistic License 2.0 (GPL Compatible)
70