App-local-lib-helper
view release on metacpan or search on metacpan
README.mkdn view on Meta::CPAN
# 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](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 --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](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](http://search.cpan.org/perldoc?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 `localenv` will make sure the same [local::lib](http://search.cpan.org/perldoc?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 `localenv` 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 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](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
README.mkdn view on Meta::CPAN
- 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 ) {
README.mkdn view on Meta::CPAN
a [local::lib](http://search.cpan.org/perldoc?local::lib) target of `/home/integration/webapp-cpan-locallib` and you
wish to copy that directory recursively to your qa/production server, which
might be located at `/home/qa/local-lib`.
I'd like to accomodate this approach as best I can, however I can't be certain
that moving Perl and [local::lib](http://search.cpan.org/perldoc?local::lib) around rather than performing a true install
is going to work consistently. Caveat emptor!
Please also note that the following shell snippets are not relative tested.
## 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](http://search.cpan.org/perldoc?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`> >
lib/App/local/lib/helper.pm view on Meta::CPAN
=head1 NAME
App::local::lib::helper - Make it easy to run code against a local-lib
=head1 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 C<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
=head1 DESCRIPTION
This is an object which provide the functionality to create a L<local::lib>
'helper' script in either the currently loaded L<local::lib> environment or in
a target directory of choice. By default the script is called C<localenv> and
can be used to invoke a command under the L<local::lib> which it was built
against. For example, assume you build a L<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 C<~/mylib> (cpanminus behind the scenes uses
L<local::lib> to do this for you) then you are telling cpanminus to install the
distribution L<App::local::lib::helper> into that created L<local::lib> directory.
When the C<Makefile.PL> script for L<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 C<~/mylib/bin> called C<localenv>.
Now, if you want to invoke a perl application and use libs installed into
C<~/mylib>, you can do so like:
~/mylib/bin/localenv perl [SOME COMMAND]
The command C<localenv> will make sure the same L<local::lib> that was active
when L<App::local::lib::helper> was originally installed is again installed
into the environment before executing the commands passed in C<@ARGV>. Upon
completing the command, the C<%ENV> is restored so that you can use this to fire
off an application against a specific L<local::lib> without needing to deal
with the details of how to activate the L<local::lib> or how to make sure
your C<%ENV> stays clean.
The arguments given to C<localenv> don't need to be a perl application. For
example, I often like to open a sub shell under a particular L<local::lib>
managed directory.
~/mylib/bin/localenv bash
Now, if I do:
perl -V
I'll see that iC<~/mylib> has been added to C<@INC>. Additionally, C<~/mylib/bin> will
have been added to C<$PATH>, so that any command line perl applications installed
into the L<local::lib> (such as C<ack> or C<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.
L<local::lib> does all the real work, but I find this to be the easiest way to
run given code against a L<local::lib> root.
=head2 Additional Helpers
In addition to the C<localenv> script which is documented above, we also create
two snippets of code suitable for including in your C<.bashrc> or C<.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 C<.bashrc>
source $TARGET/bin/localenv-bashrc
Where $TARGET is the root of your local lib (the directory that contains your
C<bin> and C<lib> directories created when you ran the helper).
Next time you log in, you can do C<perl -V> and should see that your local-lib
has automatically been activated.
There will also be a C<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.
=head1 OPTIONS
This class supports the following options.
=over 4
=item which_perl
lib/App/local/lib/helper.pm view on Meta::CPAN
=item target
This is the target directory for the L<local::lib> you want to build the helper
script against. By default it will attempt to detect the currently running
L<local::lib> and use that. If we can't detect a running L<local::lib> and
this option is undef, we die with a message.
=item helper_name
This is the name of the helper utility script. It defaults to 'localenv'.
=item 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]'
=back
=head1 HELPERS
This distribution installs the following L<local::lib> helpers
=head2 localenv
This is a perl script that runs a single command in L<local::lib> aware context.
You can use the C<helper-name> option to set a different name.
Typically I will use this to 'enable' a previously setup L<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 L<local::lib> target
and exit cleanly:
~/mylocallib/bin/localenv perl app.pl
~/mylocallib/bin/localenv plackup app.psgi
=head2 localenv-relative
NOTE: Experimental feature. Please prefer using L</localenv> unless you
absolutely need this functionality.
This perl script functions (or should function) identically to L<localenv> as
documented. However, instead of having hardcoded full paths to your Perl
binary and L<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 L</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 ) {
lib/App/local/lib/helper.pm view on Meta::CPAN
a L<local::lib> target of C</home/integration/webapp-cpan-locallib> and you
wish to copy that directory recursively to your qa/production server, which
might be located at C</home/qa/local-lib>.
I'd like to accomodate this approach as best I can, however I can't be certain
that moving Perl and L<local::lib> around rather than performing a true install
is going to work consistently. Caveat emptor!
Please also note that the following shell snippets are not relative tested.
=head2 localenv-bashrc
a snippet suitable for sourcing in your .bashrc, which will automatically
activate a local-lib at login. Name will follow from C<helper-name>.
Here's an example of the line I might add to .bashrc (assumes you have setup
L<local::lib> in C<$HOME/mylocal>
source $HOME/mylocal/localenv-bashrc
Then next time you open a shell you should see that C<$PATH> and C<PERL5LIB>
have been properly changed.
=head2 localenv-cshrc
a snippet suitable for sourcing in your .cshrc, which will automatically
activate a local-lib at login. Name will follow from C<helper-name>.
=head1 AUTHOR
John Napiorkowski C< <<jjnapiork@cpan.org>> >
=head1 COPYRIGHT & LICENSE
lib/App/local/lib/helper/rationale.pod view on Meta::CPAN
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>
script/local-lib-helper view on Meta::CPAN
use Config;
use FindBin;
use File::Spec;
use lib File::Spec->catdir($FindBin::Bin, '..', 'lib');
use App::local::lib::helper;
if( @ARGV || App::local::lib::helper->has_local_lib_env) {
my $help = 0;
my $which_perl = $ENV{LOCALLIB_HELPER_WHICH_PERL} || $Config{perlpath};
my $target = $ENV{LOCALLIB_HELPER_TARGET} || undef;
my $helper_name = $ENV{LOCALLIB_HELPER_HELPER_NAME} || 'localenv';
my $helper_permissions = $ENV{LOCALLIB_HELPER_HELPER_PERMISSIONS} || '0755';
my $result = Getopt::Long::GetOptions(
'h|help' => \$help,
'p|which_perl=s' => \$which_perl,
't|target=s' => \$target,
'n|helper_name=s' => \$helper_name,
'p|helper_permissions=s' => \$helper_permissions,
);
if($help || !$result) {
print <<'END';
Usage: perl Makefile.PL %OPTIONS
Options:
-h,--help This help message
-p,--which_perl The Perl binary we are building the helper for (default: $^X)
-t,--target The local::lib we are building the helper for (default is current)
-n,--helper_name Name of the helper script (default: localenv)
-p,--helper_permissions Permissions given to the helper script (default 775)
Type `perldoc App::local::lib::helper` or `perldoc App::local::lib::helper::rationale`
for more details.
END
} else {
App::local::lib::helper->run(
which_perl => $which_perl,
target => $target,
script/local-lib-helper view on Meta::CPAN
=item target (--target, -t)
This is the target directory for the L<local::lib> you want to build the helper
script against. By default it will attempt to detect the currently running
L<local::lib> and use that. If we can't detect a running L<local::lib> and
this option is undef, we die with a message.
=item helper_name (--helper_name, -n)
This is the name of the helper utility script. It defaults to 'localenv'.
=item helper_permissions (--helper_permissions, -p)
These are the permissions the the helper utility script is set to. By default
we set the equivilent of 'chmod 755 [HELPER SCRIPT]'
=back
=head ALSO SEE
( run in 1.654 second using v1.01-cache-2.11-cpan-ceb78f64989 )