/ 
FindApp-v0.0.2
River stage zero No dependents
/ FindApp

NAME

FindApp - find your application home and config your process for it

SYNOPSIS

use FindApp;           # defaults to "lib" argument
use FindApp "lib";     # explicit

That guarantees that this will always src, presuming there is a "lib" above you that has the "MyCorp::CorpApp" module under it:

use FindApp "MyCorp::CorpApp";
use MyCorp::CorpApp;

Or load-and-go:

use FindApp -root => "lib/", -use "MyCorp::CorpApp";

AKA:

use applib "MyCorp::CorpApp";

DESCRIPTION

When you have a application directory with its own installation instructure, setting up its @INC path for its scripts to use can be troublesome. You can't just say:

use lib "lib";

or

use lib "../lib";

because that requires that the program be run from a particular directory. The normal approach is something like this:

use FindBin;
use lib "$FindBin::Bin/../lib";

Even when possible in a few cases, it doesn't src for scripts that you want to move around your application tree, such as test files, support tools that may be in a prod-vs-nonprod directory, cron scripts, and all the rest.

When you say use FindApp, the first enclosing directory that matches the selection criteria is used. The default selection criterion is that the root application directory contain a directory called "lib", which will be added to your @INC. You can also look at the current selection criteria this way:

bash$ perl -MFindApp -le 'print FindApp->constraint_text'
lib/ in root

What it actually does is something like this:

bash$ perl -MFindApp -e 'print FindApp->shell_settings'
export APP_ROOT="/home/tchrist/src/corp-app";
export PERL5LIB="/home/tchrist/src/corp-app/lib:$PERL5LIB";
export PATH-"/home/tchrist/src/corp-app/bin:$PATH";

Except that it only does a use lib on the library directory it found; it doesn't actually muck with your PERL5LIB variable.

That's something you could eval directly from your shell. This even srcs for csh and tcsh users, because they see something different:

tcsh% perl -MFindApp -e 'print FindApp->shell_settings'
setenv APP_ROOT "/home/tchrist/src/corp-app";
setenv PERL5LIB "/home/tchrist/src/corp-app/lib:$PERL5LIB";
setenv PATH "/home/tchrist/src/corp-app/bin:$PATH";

You can add constraints to the root directory itself or the bin set, the lib set, or the man set. For example,

use FindApp -LIB "t/lib",          # add new lib possibility
            -BIN "bin/utils",      # add new bin possibility
            -bin "app.fcgi",       # add new bin requirement
            qw(MyCorp::CorpApp MyCorp::CorpApp::Test);  # add two lib requirements

The constraint text after that would be:

lib/ in root, app.fcgi in bin or bin/utils, and MyCorp::CorpApp and MyCorp::CorpApp::Test in lib or t/lib

Public Methods

Exports

EXAMPLES

ENVIRONMENT

SEE ALSO

FindApp

CAVEATS AND PROVISOS

BUGS AND LIMITATIONS

HISTORY

AUTHOR

Tom Christiansen <tchrist@perl.com>

LICENCE AND COPYRIGHT

Copyright (c) 2016, Tom Christiansen <tchrist@perl.com>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.