/ 
App-rlibperl-0.700
River stage zero No dependents
/ App::rbinperl

NAME

App::rbinperl - Execute perl using relative lib and assuming -S

VERSION

version 0.700

SYNOPSIS

Simplify cron jobs or other places where you specify commands to execute which don't have your full environment.

Instead of:

* * * * * perl -I/home/username/perl5/lib/perl5 \
                 /home/username/perl5/bin/somescript

Do:

* * * * * /home/username/perl5/bin/rbinperl somescript

This is even more useful in a shebang line which is often limited to a single argument...

This won't work on linux:

#!/usr/local/bin/perl -I/home/username/perl5/lib/perl5 -S plackup

This will:

#!/home/username/perl5/bin/rbinperl plackup

This example can be handy in a shared hosting environment where you install the modules you want using local::lib and then want to use plackup to run your app from apache as a CGI or FCGI script.

DESCRIPTION

The rbinperl script simplifies the execution of a perl script that depends on modules located in relative library directories.

This uses the same logic as App::rlibperl to prepend relative lib directories to @INC and additionally passes the -S argument to perl. This causes perl to search the $PATH (which now contains the directory where rbinperl was found) for the specified script.

EXAMPLE USAGE WITH local::lib

If you have installed App::MadeUpScript (and App::rbinperl) via local::lib your directory tree will look something like this:

${root}/bin/rbinperl
${root}/bin/made-up-script
${root}/lib/perl5/${modules}
${root}/lib/perl5/${archname}/${extras}
${root}/man/${docs}

When you're using a login shell with local::lib enabled you can just call made-up-script from the shell because your environment variables are configured such that ${root}/bin is in your $PATH and ${root}/lib/perl5 is in $PERL5LIB.

However to run from any sort of detached process the environment variables from local::lib won't be available, and you'd have to do this instead:

$ perl -I${root}/lib/perl5 -S made-up-script

rbinperl simplifies this by adding the relative lib directories automatically and passing -S:

$ ${root}/bin/rbinperl made-up-script

BLAH BLAH BLAH

Honestly the script itself is much simpler than explaining how it can be useful (if it even is useful).

USE CASE

SHARED HOSTING

One of the reasons for creating this dist was to make it as easy as possible to install a modern perl web framework into a shared hosting environment.

You can build a web application and use Plack to run it as fastcgi through Apache (a common shared hosting option).

For example you could put this in dispatch.fcgi:

#!/usr/bin/env plack
require 'mywebapp.pl';

and Apache would run your perl script through plack which would detect an FCGI environment and then load your web app.

If plack and your web framework are installed into a local lib this won't work. Instead you can do this:

#!/home/username/perl5/bin/rbinperl plackup
require 'mywebapp.pl';

It's almost as easy, and makes the rest (loading your local lib) transparent.

BUGS AND LIMITATIONS

Unfortunately the shebang described above isn't entirely portable.

If you are on an operating system that doesn't allow using another script (as opposed to a binary) in the shebang, you may be able to use a work around like this instead:

#!/bin/sh
eval 'exec perl /home/username/perl5/bin/rbinperl plackup $0 ${1+"$@"}'
  if 0;
require 'mywebapp.pl';

It's a slight variation of a common perl/shebang idiom.

See "BUGS AND LIMITATIONS" in App::rlibperl for more.

SEE ALSO

AUTHOR

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Randy Stauner.

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