view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

have been added to `$PATH`, so that any command line perl applications installed
into the [local::lib](http://search.cpan.org/perldoc?local::lib) (such as `ack` or `cpanm`) can be accessed easily.

Another example usage would be when you want to install an application from
CPAN, install it and all its dependencies to a single directory root and 
then run it without a lot of effort.  For example:

    cpanm --local-lib ~/gitalyst-libs Gitalist App::local::lib::helper
    ~/gitalyst-libs/bin/localenv gitalyst-server.pl

And presto! Your cpan installed application is running, fully self-contained to
one root directory all under regular user privileges.

[local::lib](http://search.cpan.org/perldoc?local::lib) does all the real work, but I find this to be the easiest way to
run given code against a [local::lib](http://search.cpan.org/perldoc?local::lib) root.  

## Additional Helpers

In addition to the `localenv` script which is documented above, we also create
two snippets of code suitable for including in your `.bashrc` or `.cshrc`.
These are created to help people that only want or need a single local lib and
would like to activate it at login.  If you'd like to use these, simple add the
following tot he end of your `.bashrc`

    source $TARGET/bin/localenv-bashrc

Where $TARGET is the root of your local lib (the directory that contains your
`bin` and `lib` directories created when you ran the helper).

Next time you log in, you can do `perl -V` and should see that your local-lib
has automatically been activated.

There will also be a `source $TARGET/bin/localenv-cshrc` created for those of
you using csh.  Currently this is not going to work with Windows shell users,
but should be easy to setup, collaborations very welcomed.

# OPTIONS

This class supports the following options.

- which_perl

This should be the path to the perl binary that the [local::lib](http://search.cpan.org/perldoc?local::lib) is built
against. This defaults to the path of the perl binary under which we are
currently running.  You should probably leave this one alone :)

- target

This is the target directory for the [local::lib](http://search.cpan.org/perldoc?local::lib) you want to build the helper
script against.  By default it will attempt to detect the currently running
[local::lib](http://search.cpan.org/perldoc?local::lib) and use that.  If we can't detect a running [local::lib](http://search.cpan.org/perldoc?local::lib) and
this option is undef, we die with a message.

- helper_name

This is the name of the helper utility script.  It defaults to 'localenv'.

- helper_permissions

These are the permissions the the helper utility script is set to.  By default
we set the equivilent of 'chmod 755 [HELPER SCRIPT]'

# HELPERS

This distribution installs the following [local::lib](http://search.cpan.org/perldoc?local::lib) helpers

## localenv

This is a perl script that runs a single command in [local::lib](http://search.cpan.org/perldoc?local::lib) aware context.
You can use the `helper-name` option to set a different name.

Typically I will use this to 'enable' a previously setup [local::lib](http://search.cpan.org/perldoc?local::lib) with
commands like:

    ~/mylocallib/bin/localenv bash
    ~/mylocallib/bin/localenv screen

Or I can use it to run a single command wrapped in the [local::lib](http://search.cpan.org/perldoc?local::lib) target
and exit cleanly:

    ~/mylocallib/bin/localenv perl app.pl
    ~/mylocallib/bin/localenv plackup app.psgi

## localenv-relative

NOTE: Experimental feature.  Please prefer using [localenv](#pod_localenv) unless you 
absolutely need this functionality.

This perl script functions (or should function) identically to [localenv](http://search.cpan.org/perldoc?localenv) as
documented.  However, instead of having hardcoded full paths to your Perl
binary and [local::lib](http://search.cpan.org/perldoc?local::lib) target directories, we instead try to use relative
pathing.  For example, here is the helper script built on my server for the
standard [localenv](#pod_localenv) script:

    #!/Users/johnn/perl5/perlbrew/perls/perl-5.14.1/bin/perl

    use strict;
    use warnings;

    use lib '/Users/johnn/locallib_5_14_1/lib/perl5';
    use local::lib '/Users/johnn/locallib_5_14_1';

    unless ( caller ) {
        if ( @ARGV ) {
            exec @ARGV;
        }
    }

And here is the example same version for the relative script:

    #!/usr/bin/env perl

    use strict;
    use warnings;

    use FindBin;
    use File::Spec;
    use lib File::Spec->catdir($FindBin::Bin, '..', 'lib', 'perl5');
    use local::lib File::Spec->catdir($FindBin::Bin, '..');

    unless ( caller ) {