# NAME App::local::lib::helper - Make it easy to run code against a 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/localenv perl [SOME COMMAND] The command `locallib` will make sure the same L 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/localenv 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. ## 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 you bin and lib directories). 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. ## 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`. ## 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 ` < > # 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.