NAME

lib::projectroot - easier loading of a project's local libs

VERSION

version 1.001

SYNOPSIS

# your_project/bin/somewhere/deep/down/script.pl
use strict;
use warnings;
# look up from the file's location until we find a directory
# containing a directory named 'lib'. Add this dir to @INC
use lib::projectroot qw(lib);

# look up until we find a dir that contains both 'lib' and 'foo',
# add both to @INC
use lib::projectroot qw(lib foo);

# look up until we find 'lib' and 'local'. Add 'lib' to @INC,
# load 'local' via local::lib
use lib::projectroot qw(lib local::lib=local);

# based on the dir we found earlier, go up one dir and try to add
# 'Your-OtherModule/lib' and 'Dark-PAN/lib' to @INC
lib::projectroot->load_extra(Your-OtherModule Dark-PAN);

DESCRIPTION

I'm usually using a setup like this:

.
├── AProject
│   ├── bin
│   │   ├── db
│   │   │   └── init.pl
│   │   ├── onetime
│   │   │   ├── fixup
│   │   │   │   └── RT666_fix_up_fubared_data.pl
│   │   │   └── import_data.pl
│   │   └── web.psgi
│   ├── lib
│   └── local
├── MyHelperStuff
│   └── lib
└── CoolLib-NotYetOnCPAN
    └── lib

There is AProject, which is the actual code I'm working on. There is also probably BProject, e.g. another microservice for the same customer. AProject has it's own code in lib and it's CPAN dependencies in local (managed via Carton and used via local::lib). There are a bunch of scripts / "binaries" in bin, in a lot of different directories of varying depth.

I have some generic helper code I use in several projects in MyHelperStuff/lib. It will never go to CPAN. I have some other code in CoolLib-NotYetOnCPAN/lib (but it might end up on CPAN if I ever get to clean it up...)

lib::projectroot makes it easy to add all these paths to @INC so I can use the code.

In each script, I just have to say:

use lib::projectroot qw(lib local::lib=local);

lib is added to the beginning of <@INC>, and local is loaded via local::lib, without me having to know how deep in bin the current script is located.

I can also add

lib::projectroot->load_extra(qw(MyHelperStuff CoolLib-NotYetOnCPAN));

to get my other code pushed to @INC. (Though currently I put this line, and some other setup code like initialising Log::Any into AProject::Run, and just use AProject::Run;)

TODOs

Some ideas for future releases:

• what happens if $PERL5LIB is already set?

• add local::lib dirs of extras (i.e. if DarkPAN also uses local::lib to install it's deps)

• also load extras via lib::projectroot's import method

• think about the security issues raised by Abraxxa (http://prepan.org/module/nY4oajhgzJN 2014-12-02 18:42:07)

SEE ALSO

• FindBin - find out where the current binary/script is located, but no @INC manipulation. In the Perl core since forever. Also used by lib::projectroot.

• Find::Lib - combines FindBin and lib, but does not search for the actual location of lib, so you'll need to know where your scripts is located relative to lib.

• FindBin::libs - finds the next lib directory and uses it, but no local::lib support. But lots of other features

• File::FindLib - find and use a file or dir based on the script location. Again no local::lib support.

• and probably more...

THANKS

Thanks to eserte, Smylers & Ca<abraxxa> for providing feedback at http://prepan.org/module/nY4oajhgzJN|prepan.org. Meta-thanks to http://twitter.com/kentaro|kentaro for running prepan, a very handy service!

Thanks to koki, farhad and Jozef for providing face-to-face feedback.

AUTHOR

Thomas Klausner <domm@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Thomas Klausner.

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

cpanm lib::projectroot

perl -MCPAN -e shell
install lib::projectroot