.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "lib::relative 3pm"
.TH lib::relative 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lib::relative \- Add paths relative to the current file to @INC
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  # Path is relative to this file, not current working directory
\&  use lib::relative \*(Aqpath/to/lib\*(Aq;
\&  use lib::relative \*(Aq../../lib\*(Aq;
\&  
\&  # Add two lib paths, as in lib.pm
\&  use lib::relative \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq;
\&  
\&  # Absolute paths are passed through unchanged
\&  use lib::relative \*(Aqfoo/baz\*(Aq, \*(Aq/path/to/lib\*(Aq;
\&  
\&  # 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_\|_), \*(Aqpath/to/lib\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Adding a path to \f(CW@INC\fR 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 \f(CW@INC\fR means that any later code that changes the current
working directory will change where modules are loaded from. This applies to
the \f(CW\*(C`.\*(C'\fR path that used to be in \f(CW@INC\fR by default until perl 5.26.0, or a
relative path added in code like \f(CW\*(C`use lib \*(Aqpath/to/lib\*(Aq\*(C'\fR, 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
\&\f(CW@INC\fR.
.PP
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.
.PP
For cases where this module cannot be loaded beforehand, the last section of
the \*(L"\s-1SYNOPSIS\*(R"\s0 can be copy-pasted into a file to perform the same task.
.SH "CAVEATS"
.IX Header "CAVEATS"
Due to \f(CW\*(C`_\|_FILE_\|_\*(C'\fR possibly being a path relative to the current working
directory, be sure to use \f(CW\*(C`lib::relative\*(C'\fR or the equivalent code from
\&\*(L"\s-1SYNOPSIS\*(R"\s0 as early as possible in the file. If a \f(CW\*(C`chdir\*(C'\fR occurs before
this code, it will add the incorrect directory path.
.PP
All file paths are expected to be in a format appropriate to the current
operating system, e.g. \f(CW\*(C`..\e\efoo\e\ebar\*(C'\fR on Windows. \*(L"catdir\*(R" in File::Spec can
be used to form directory paths portably.
.SH "BUGS"
.IX Header "BUGS"
Report any issues on the public bugtracker.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dan Book <dbook@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2017 by Dan Book.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
lib, FindBin, Dir::Self