| PackageDescription | Adding a path to perlvar/"@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 the FindBin manpage 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 perldata/"Special Literals", absolutize
it, and add it to '@INC'.
If this module is already available to be loaded, it can be used as with
the lib manpage.pm, passing relative paths, which will be absolutized
relative to the current file then passed on to the lib manpage. 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 the /"SYNOPSIS" manpage can be copy-pasted into a file to perform
the same task. |