view release on metacpan or  search on metacpan

lib/App/local/lib/helper/rationale.pod  view on Meta::CPAN

    $VAR16 = '/opt/local/sbin';

Note the directory C</Users/johnn/perl5/perlbrew/perls/current/bin> is in C<$PATH>
This is so that any command line utilities installed by CPAN (such as L<App::Ack>)
will be easy to find and not require you to type in the full path to that tool.

Now, when you create a L<local::lib>, Perl has no way to automatically detect
it.  Perhaps it would be cool if a future version of Perl could notice the
presence of a L<local::lib> and add it automatically, but that's not today.  As
of now you need to tell Perl to modify C<@INC> and C<$PATH> in such a way as that it
can use your locally lib installed dependencies.

The documentation for L<local::lib> recommends adding a bit of code to your 
C<.bashrc> script (assuming you are on a Unixlike system.)  This works well if
you only have a single L<local::lib> setup, however if you are like me and
you create a new L<local::lib> per application this is not going to work very
well.  You need a way to 'flip' a L<local::lib> on and off as you move from
one project to another.  Additionally, for the purposes of deployment, you may
wish for something that requires less setup.

One option is to manually 'activate' a particular local lib for each perl
command you run.

    perl -I ~/mylib/lib/perl5 -Mlocal::lib=~/mylib [COMMAND]

You can see it work like so:

    $ perl -I ~/mylib/lib/perl5/ -Mlocal::lib=~/mylib/ -e 'use Data::Dumper; warn Dumper @INC, split(":",$ENV{PATH})'
    $VAR1 = '/Users/johnn/mylib/lib/perl5/darwin-thread-multi-2level';
    $VAR2 = '/Users/johnn/mylib/lib/perl5';
    $VAR5 = '/Users/johnn/perl5/perlbrew/perls/perl-5.10.1/lib/5.10.1/darwin-thread-multi-2level';
    $VAR6 = '/Users/johnn/perl5/perlbrew/perls/perl-5.10.1/lib/5.10.1';
    $VAR7 = '/Users/johnn/perl5/perlbrew/perls/perl-5.10.1/lib/site_perl/5.10.1/darwin-thread-multi-2level';
    $VAR8 = '/Users/johnn/perl5/perlbrew/perls/perl-5.10.1/lib/site_perl/5.10.1';
    $VAR9 = '.';
    $VAR10 = '/Users/johnn/mylib/bin';
    $VAR11 = '/Users/johnn/perl5/perlbrew/bin';
    $VAR12 = '/Users/johnn/perl5/perlbrew/perls/current/bin';
    $VAR13 = '/usr/bin';
    $VAR14 = '/bin';
    $VAR15 = '/usr/sbin';
    $VAR16 = '/sbin';
    $VAR17 = '/usr/local/bin';
    $VAR18 = '/usr/local/git/bin';
    $VAR19 = '/usr/X11/bin';
    $VAR20 = '/opt/local/bin';
    $VAR21 = '/opt/local/sbin';

As you can see, the local lib is now added to C<@INC> and C<$PATH> has been altered.
Additionally, a few other perl C<%ENV> settings are created so that L<CPAN> knows
where to install dependencies.

This is a workable option for deployment, since you are probably scripting that
and have limited interactivity needs.  However it is onerous for developers.

Making it easier for developers is the basic reason for being for this
application.  The created helper script wraps the above effort into a single
and hopefully short command.  Additionally, its not limited to Perl commands.
So you can use it like:

    ~/mylib/bin/localenv bash

And spawn off a subshell where your C<@INC>, C<$PATH> and other important bits have
been properly setup.  You can then exit the shell when you need to cancel the
alterations.  Or you can just use the command like

    ~/mylib/bin/localenv perl -V

And you get the expected output.  I personally find this easier but your results
may differ.  Feedback and thoughts regarding improvements very welcomed.

=head1 EXAMPLES

The following are some example usage for this application

=head2 Setting up a development environment

Let's say you clone some application down from L<http://github.com> and you are going to
start development.  You will need to setup a L<local::lib> of that applications
dependencies as part of your job.  You can do so like (from the directory that
contains the application C<Makefile.PL>)

    curl -L http://cpanmin.us | perl - --local-lib ~/mylib App::local::lib::helper .

and then you can use the bash trick from above to flip on your local lib
environment:

    ~/mylib/bin/localenv bash

and then you can start working, running code, or even adding to the dependency
list.

=head2 Installing / Deploying an application

Say you want to install an application from L<CPAN> and just run it on a shared
server.  Let's assume you have very little or no control beyond your C<$HOME>
directory.

    curl -L http://cpanmin.us | perl - --local-lib ~/mygitalist Gitalist App::local::lib::helper

Here we are running cpanminus directly off the web, installing L<Gitalist>, a
L<Catalyst> based git web front end, and setting up a local lib helper for it.

We can then startup L<Gitalist>:

    ~/mygitalist/bin/localenv gitalist_server.pl --repo_dir $REPO

Hopefully this eases some of your deployment issues!

=head2 Using in an applicatin or module Makefile.PL

If you add this as a requirement to your C<Makefile.PL> and it is installed into
a C<local::lib> the helper will automatically be added.

Example C<Makefile.PL>

    #!/usr/bin/env perl

    use strict;
    use warnings FATAL => 'all';
    use inc::Module::Install;

    requires 'App::local::lib::helper';
    ## rest of your file

=head1 AUTHOR

See L<App::local::lib::helper> for Authorship information

=head1 COPYRIGHT & LICENSE

See L<App::local::lib::helper> for Copyright and Licensing information.

=cut