lib::relative(3)

✨ lib::relative(3) — the perl one, bestie ✨

okay so first things first, this is a page from the User Contributed Perl Documentation section of the manual (that's the perl manual, section 3), and it's about a module called lib::relative. buckle up 💅

---

🌸 NAME 🌸

lib::relative — adds paths to @INC that are relative to the current file 🎀

🌈 SYNOPSIS 🌈

like, here's the whole vibe in code form:

  # 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 💖

okay so adding a path to @INC so you can load modules out of a local directory sounds like the easiest thing ever, right? wrong, bestie 😭 there are a few iconic pitfalls and you Need to know about them.

if you just plop a relative path straight into @INC, then any code that runs later and changes the current working directory will legit change where your modules get loaded from. yikes. and this applies to both:

• the "." path that used to be in @INC by default until perl 5.26.0, and
• any relative path you add in code like use lib 'path/to/lib'

and ngl, that can be a whole vulnerability if that location isn't supposed to be writable 👀

also, the super commonly used FindBin module? it relies on interpreter state and on the path to the original script that the perl interpreter was invoked with, which sometimes means you need workarounds in uncommon cases — like generated code, or embedded code. not it 🙈

so this module proposes a much more straightforward method: take a path relative to the current file, absolutize it, and add it to @INC. periodt ✨

if this module is already available to be loaded, you can use it exactly like lib.pm — pass it relative paths and they get absolutized relative to the current file, then passed on to lib. multiple arguments each get absolutized separately, and absolute paths are passed on unchanged. slay 🫶

and for the cases where you can't load this module beforehand? the last chunk of the SYNOPSIS can literally just be copy-pasted into your file to do the exact same task. no cap.

💀 CAVEATS 💀

because __FILE__ might be a path that's relative to the current working directory, you gotta use lib::relative (or the equivalent code from SYNOPSIS) as early as possible in the file. seriously. if a chdir happens before that code runs, it will add the totally incorrect directory path. 😬

also, all file paths are expected to be in a format that's appropriate for the current operating system — e.g. ..\foo\bar on Windows. you can use catdir in File::Spec to form directory paths portably. 🧚

🦋 BUGS 🦋

report any issues on the public bugtracker. that's it, that's the whole section 💜

👑 AUTHOR 👑

Dan Book <dbook@cpan.org>

🎀 COPYRIGHT AND LICENSE 🎀

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

it's free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

⭐ SEE ALSO ⭐

lib, FindBin, Dir::Self

---

and that's the whole page, bestie 🫶 this was perl v5.42.0, dated 2024-03-08, and it's the lib::relative(3) page — go forth and absolutize your paths 💖✨