# NAME

App::local::lib::helper - Make it easy to run code against a [local::lib](http://search.cpan.org/perldoc?local::lib)

# SYNOPSIS

    use App::local::lib::helper;
    App::local::lib::helper->run(%opts);

# DESCRIPTION

This is an object which provide the functionality to create a [local::lib](http://search.cpan.org/perldoc?local::lib)
'helper' script in either the currently loaded [local::lib](http://search.cpan.org/perldoc?local::lib) environment or in
a target directory of choice.  By default the script is called 'localenv' and
can be used to invoke a command under the [local::lib](http://search.cpan.org/perldoc?local::lib) which it was built
against.  For example, assume you build a [local::lib](http://search.cpan.org/perldoc?local::lib) like so:

    cpanm -L ~/mylib App::local::lib::helper

Note what is happening.  First, you are telling cpanminus to install everything
to a local::lib directory called "~/mylib" (cpanminus behind the scenes uses
[local::lib](http://search.cpan.org/perldoc?local::lib) to do this for you) then you are telling cpanminus to install the
distribution [App::local::lib::helper](http://search.cpan.org/perldoc?App::local::lib::helper) into that created local lib directory.
When the Makefile.PL script for [App::local::lib::helper](http://search.cpan.org/perldoc?App::local::lib::helper) runs, it notices
the fact that it is being asked to install into a locally lib managed directory
and will additionally generate a helper script into "~/mylib/bin" called "localenv".

Now, if you want to invoke a perl application and use libs installed into 
"~/mylib", you can do so like:

    ~/mylib/bin/locallib perl [SOME COMMAND]

The command `locallib` will make sure the same L<local:lib> that was active
when [App::local::lib::helper](http://search.cpan.org/perldoc?App::local::lib::helper) was originally installed is again installed
into the environment before executing the commands passed in @ARGV.  Upon
completing the command, the %ENV is restored so that you can use this to fire
off an application against a specific [local::lib](http://search.cpan.org/perldoc?local::lib) without needing to deal
with the details of how to activate the [local::lib](http://search.cpan.org/perldoc?local::lib) or how to make sure
your %ENV stays clean.

The arguments given to `locallib` don't need to be a perl application.  For
example, I often like to open a sub shell under a particular [local::lib](http://search.cpan.org/perldoc?local::lib)
managed directory.

    ~/mylib/bin/locallib bash

Now, if I do:

    perl -V

I'll see that ~/mylib has been added to @INC.  Additionally, "~/mylib/bin" will
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 -L ~/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.  

# 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]'

# AUTHOR

John Napiorkowski ` <<jjnapiork@cpan.org`> >

# COPYRIGHT & LICENSE

Copyright 2010, John Napiorkowski

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