NAME
App::local::lib::helper - Make it easy to run code against a local-lib
SYNOPSIS
Installing and using the helper (common usage)
cpanm --local-lib ~/mylib App::local::lib::helper
~/mylib/bin/localenv bash
Customizing the helper creation (advanced use only)
use App::local::lib::helper;
App::local::lib::helper->run(%opts);
Note, if you don't have cpanm already installed you can use the web service
version like so instead for all examples:
curl -L http://cpanmin.us/ | perl - --local-lib ~/mylib App::local::lib::helper
DESCRIPTION
This is an object which provide the functionality to create a local::lib
'helper' script in either the currently loaded 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 which it was built
against. For example, assume you build a local::lib like so:
cpanm --local-lib ~/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 to do this for you) then you are telling cpanminus to install the
distribution App::local::lib::helper into that created local::lib directory.
When the Makefile.PL script for 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/localenv perl [SOME COMMAND]
The command localenv will make sure the same Llocal:lib that was active
when 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 without needing to deal
with the details of how to activate the local::lib or how to make sure
your %ENV stays clean.
The arguments given to localenv don't need to be a perl application. For
example, I often like to open a sub shell under a particular local::lib
managed directory.
~/mylib/bin/localenv bash
Now, if I do:
perl -V
I'll see that i~/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 (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 does all the real work, but I find this to be the easiest way to run given code against a 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 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 you want to build the helper script against. By default it will attempt to detect the currently running local::lib and use that. If we can't detect a running 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 helpers
localenv
This is a perl script that runs a single command in 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 with commands like:
~/mylocallib/bin/localenv bash
~/mylocallib/bin/localenv screen
localenv-bashrc
a snippet suitable for sourcing in your .bashrc, which will automatically
activate a local-lib at login. Name will follow from helper-name.
Here's an example of the line I might add to .bashrc (assumes you have setup
local::lib in $HOME/mylocal
source $HOME/mylocal/localenv-bashrc
Then next time you open a shell you should see that $PATH and PERL5LIB
have been properly changed.
localenv-cshrc
a snippet suitable for sourcing in your .cshrc, which will automatically
activate a local-lib at login. Name will follow from helper-name.
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.