# NAME lib::projectroot - easier loading of a project's local libs # VERSION version 1.009 # 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); # the same as above use lib::projectroot qw(lib local::lib=local extra=Your-OtherModule,Dark-PAN); # if you want to know where the project-root is: say $lib::projectroot::ROOT; # /home/domm/jobs/Some-Project # also load local::libs installed in extras use lib::projectroot qw(lib local::lib=local extra_with_local=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 its own code in `lib` and its 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;`) You can also define extra dists directly while loading `lib::projectroot`: use lib::projectroot qw( lib local::lib=local extra=MyHelperStuff,CoolLib-NotYetOnCPAN ); If your extra dists themselves have deps which are installed into their `local::lib`, you can add those via `extra_with_local`: use lib::projectroot qw( lib local::lib=local extra=MyHelperStuff extra_with_local=CoolLib-NotYetOnCPAN ); You can access `$lib::projectroot::ROOT` if you need to know where the projectroot actually is located (e.g. to load some assets) # TODOs Some ideas for future releases: - what happens if `$PERL5LIB` is already set? - think about the security issues raised by Abraxxa (http://prepan.org/module/nY4oajhgzJN 2014-12-02 18:42:07) # SEE ALSO - [FindBin](https://metacpan.org/pod/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](https://metacpan.org/pod/Find%3A%3ALib) - 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](https://metacpan.org/pod/FindBin%3A%3Alibs) - finds the next `lib` directory and uses it, but no [local::lib](https://metacpan.org/pod/local%3A%3Alib) support. But lots of other features - [File::FindLib](https://metacpan.org/pod/File%3A%3AFindLib) - find and use a file or dir based on the script location. Again no [local::lib](https://metacpan.org/pod/local%3A%3Alib) support. - and probably more... # THANKS Thanks to `eserte`, `Smylers` & `abraxxa` for providing feedback at [prepan.org](http://prepan.org/module/nY4oajhgzJN). Meta-thanks to [kentaro](http://twitter.com/kentaro) for running prepan, a very handy service! Thanks to `koki`, `farhad` and `Jozef` for providing face-to-face feedback. # AUTHOR Thomas Klausner # COPYRIGHT AND LICENSE This software is copyright (c) 2014 - 2021 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.