lib::abs(3)

Okay bestie, welcome to the lib::abs(3) glow-up — it’s a User Contributed Perl Documentation page, and it’s here to make your relative paths absolutely iconic. 💅✨

💖 NAME 💖

lib::abs — the "lib" that makes relative path absolute to caller. 🎀

🦋 SYNOPSIS 🦋

Simple use, like "use lib ...":

use lib::abs qw(./mylibs1 ../mylibs2);
use lib::abs 'mylibs';

# if your path may not exists and it is ok, then:
use lib::abs -soft => qw(./mylibs1 ../mylibs2);

Extended syntax (glob) 🌀

use lib::abs 'modules/*/lib';

There’s also a helper function you can use from lib::abs (check example/ex4):

use lib::abs;
# ...
my $path = lib::abs::path('../path/relative/to/me'); # returns absolute path

🌸 DESCRIPTION 🌸

The main reason this library exists is to transform relative paths into absolute paths at the BEGIN stage, then push the transformed paths into @INC. The basis for a relative path is not the current working directory — it’s the location of the file where the statement lives, aka the caller file. 👑

When you use regular lib, relative paths stay relative to the current working directory instead. 🙈

# For ex:
# script: /opt/scripts/my.pl
use lib::abs '../lib';

# We run `/opt/scripts/my.pl` having cwd /home/mons
# The @INC will contain '/opt/lib';

# We run `./my.pl` having cwd /opt
# The @INC will contain '/opt/lib';

# We run `../my.pl` having cwd /opt/lib
# The @INC will contain '/opt/lib';

This module is also a lifesaver when you’re writing tests and want to load strictly the module from ../lib, respecting the test file. 🧚

# t/00-test.t
use lib::abs '../lib';

It’s also useful when you’re running under mod_perl, using something like Apache::StatINC, and your application may change its working directory. Because in the case of chdir, StatINC fails to reload the module if @INC contains relative paths. 😭

🌈 RATIONALE 🌈

Q: We already have FindBin and lib, why we need this module?

A: There are several reasons:

1. FindBin could find the path incorrectly under mod_perl.
2. FindBin works relatively to the executed binary instead of relatively to the caller.
3. Perl is a linguistic language, and use lib::abs "..." is semantically more clear and looks more beautiful than use FindBin; use lib "$FindBin::Bin/../lib";.
4. FindBin will work incorrectly if it’s called not from the executed binary (see http://github.com/Mons/lib-abs-vs-findbin comparison for details).

💀 BUGS 💀

None known. (Iconic, honestly.) ✨

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2007-2020 by Mons Anderson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

👑 AUTHOR 👑

Mons Anderson, "<mons@cpan.org>"

🫶 CONTRIBUTORS 🫶

Oleg Kostyuk, "<cub@cpan.org>"

---

💌 Baked with perl v5.42.2 on 2026-02-15 — lib::abs(3), signing off! 💅