view release on metacpan or  search on metacpan

lib/App/rlibperl.pm  view on Meta::CPAN

Upon execution the script will look for lib directories
relative to the location of the script
then re-invoke perl with all supplied command line arguments
and any found lib directories added to C<@INC>.

The script was designed to be installed via L<local::lib>
(though L<local::lib> is not required).
Once installed, executing the script is just like
executing perl except that it adds the local lib directories
to C<@INC> for you.

It also adds the directory of the script to C<$PATH>
like L<local::lib> does which enables C<system>/C<qx>/C<exec>/etc.
to find executables in that directory.

So this:

  $HOME/perl5/bin/rlibperl -MSome::Module -e 'do_something'

is roughly the equivalent of:

  PATH=$HOME/perl5/bin:$PATH perl \
     -I$HOME/perl5/lib/perl5 -MSome::Module -e 'do_something'

If that isn't useful enough (it probably isn't)
check out L<App::rbinperl> which automatically adds C<-S>
which makes it just as easy to execute another
script in that bin directory.

=head1 DIRECTORY STRUCTURES

C<rlibperl> will look for the following directory structures
relative to the directory in which it is located:

If the script is located in a directory named C<bin>
(or C<script> or C<scripts>)
it assumes a structure similar to L<local::lib>
and will first look for
C<../lib/perl5>:

  ${root}/bin/rlibperl
  ${root}/lib/perl5

If not found it will check for C<./lib>.

  ${root}/rlibperl
  ${root}/lib

(If C<rlibperl> is not located in a directory matching C</bin|scripts?/>
the order will be reversed: it will look for C<./lib> first.)

Lastly it will check for simply C<../lib>.

  ${root}/bin/rlibperl
  ${root}/lib

If you have another directory structure you think should be supported
please send suggestions!

=head1 BUGS AND LIMITATIONS

The initial use-case for C<rlibperl> was
installing via L<local::lib>
(or without it using something like C<cpanm --local-lib /other/dir>)
and calling like so:

  $ /path/to/local-lib/rlibperl -perl-args

(It may also be useful in a per-project setting,
though it's likely easier to make custom scripts
and/or use the unrelated L<rlib>.)

The following limitations exist when used in other situations,
however they are considered bugs and may be "fixed" at some point
(so their functionality should not be relied upon):

=over 4

=item *

Installing this into a perl's default lib will end up duplicating
directories in C<@INC> and probably reverse the order of your search path.

This is a problem, but then installing C<rlibperl> into a directory
that is already in your C<@INC> isn't all that useful.

=item *

Using these scripts in the shebang is arguably the most useful
way to use them (and in fact the reason they were created).

Unfortunately shebangs aren't always portable.

Some systems don't allow using another script
(as opposed to a binary) in the shebang line.
You can work around this
by adding a slight variation of the common C<eval 'exec'> idiom.
Just insert what would have been your shebang into the exec arguments:

  #!/bin/sh
  eval 'exec perl /home/username/perl5/bin/rlibperl -S $0 ${1+"$@"}'
    if 0;

=back

If you think other functionality would be useful
please submit examples, rationale, or B<patches>.

=head1 SEE ALSO

=over 4

=item *

L<App::rbinperl> - included

=item *

L<local::lib> - The module that makes this one useful