Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Replace useless README.pod with generated README.mkdn

  • Loading branch information...
commit 71b339fb9e0eb3bb75af760bd2d4ffe347f66c8a 1 parent c8683d9
@rwstauner authored
Showing with 225 additions and 33 deletions.
  1. +225 −0 README.mkdn
  2. +0 −33 README.pod
View
225 README.mkdn
@@ -0,0 +1,225 @@
+# NAME
+
+App::rlibperl - Execute perl prepending relative lib to @INC
+
+# VERSION
+
+version 0.700
+
+# SYNOPSIS
+
+Install this into a [local::lib](http://search.cpan.org/perldoc?local::lib) directory
+to simplify including the `local::lib` when calling perl:
+
+ # cron job:
+ * * * * * /project/dir/bin/rlibperl -MProject::App -e 'run()'
+
+ # program configuration file:
+ command = /home/username/perl5/bin/rlibperl -MSome::Mod -e 'do { something; }'
+
+If you're lazy (like me) you can use it in the shebang line:
+
+ #!/home/username/perl5/bin/rlibperl
+
+Then you don't need to add an explicit
+
+ use lib '/home/username/perl5/lib/perl5';
+
+before any of your other code.
+
+# DESCRIPTION
+
+The `rlibperl` script simplifies the inclusion of
+relative library directories with perl.
+
+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 `@INC`.
+
+The script was designed to be installed via [local::lib](http://search.cpan.org/perldoc?local::lib)
+(though [local::lib](http://search.cpan.org/perldoc?local::lib) is not required).
+Once installed, executing the script is just like
+executing perl except that it adds the local lib directories
+to `@INC` for you.
+
+It also adds the directory of the script to `$PATH`
+like [local::lib](http://search.cpan.org/perldoc?local::lib) does which enables `system`/`qx`/`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 [App::rbinperl](http://search.cpan.org/perldoc?App::rbinperl) which automatically adds `-S`
+which makes it just as easy to execute another
+script in that bin directory.
+
+# DIRECTORY STRUCTURES
+
+`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 `bin`
+(or `script` or `scripts`)
+it assumes a structure similar to [local::lib](http://search.cpan.org/perldoc?local::lib)
+and will first look for
+`../lib/perl5`:
+
+ ${root}/bin/rlibperl
+ ${root}/lib/perl5
+
+If not found it will check for `./lib`.
+
+ ${root}/rlibperl
+ ${root}/lib
+
+(If `rlibperl` is not located in a directory matching `/bin|scripts?/`
+the order will be reversed: it will look for `./lib` first.)
+
+Lastly it will check for simply `../lib`.
+
+ ${root}/bin/rlibperl
+ ${root}/lib
+
+If you have another directory structure you think should be supported
+please send suggestions!
+
+# BUGS AND LIMITATIONS
+
+The initial use-case for `rlibperl` was
+installing via [local::lib](http://search.cpan.org/perldoc?local::lib)
+(or without it using something like `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 [rlib](http://search.cpan.org/perldoc?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):
+
+- Installing this into a perl's default lib will end up duplicating
+directories in `@INC` and probably reverse the order of your search path.
+
+This is a problem, but then installing `rlibperl` into a directory
+that is already in your `@INC` isn't all that useful.
+
+- 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 `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;
+
+If you think other functionality would be useful
+please submit examples, rationale, or __patches__.
+
+# SEE ALSO
+
+- [App::rbinperl](http://search.cpan.org/perldoc?App::rbinperl) - included
+- [local::lib](http://search.cpan.org/perldoc?local::lib) - The module that makes this one useful
+- [ylib](http://search.cpan.org/perldoc?ylib) (`perl -Mylib`) - Configurable additional lib directories
+- [Devel::Local](http://search.cpan.org/perldoc?Devel::Local) - An alternative to the above modules
+- [rlib](http://search.cpan.org/perldoc?rlib) - This module is not related to or dependent on [rlib](http://search.cpan.org/perldoc?rlib)
+but it serves a similar purpose in a different situation.
+- [App::local::lib::helper](http://search.cpan.org/perldoc?App::local::lib::helper) - A more configurable alternative to this dist
+that loads [local::lib](http://search.cpan.org/perldoc?local::lib) and its environment variables.
+
+The `localenv` script installed by [App::local::lib::helper](http://search.cpan.org/perldoc?App::local::lib::helper)
+may be more powerful as a shell tool,
+but `rlibperl` serves a few niches that `localenv` does not,
+including enabling shebang args and taint mode.
+
+Use the tool that works for you.
+
+# SUPPORT
+
+## Perldoc
+
+You can find documentation for this module with the perldoc command.
+
+ perldoc App::rlibperl
+
+## Websites
+
+The following websites have more information about this module, and may be of help to you. As always,
+in addition to those websites please use your favorite search engine to discover more resources.
+
+- Search CPAN
+
+The default CPAN search engine, useful to view POD in HTML format.
+
+[http://search.cpan.org/dist/App-rlibperl](http://search.cpan.org/dist/App-rlibperl)
+
+- RT: CPAN's Bug Tracker
+
+The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
+
+[http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-rlibperl](http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-rlibperl)
+
+- CPAN Ratings
+
+The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
+
+[http://cpanratings.perl.org/d/App-rlibperl](http://cpanratings.perl.org/d/App-rlibperl)
+
+- CPAN Testers
+
+The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
+
+[http://www.cpantesters.org/distro/A/App-rlibperl](http://www.cpantesters.org/distro/A/App-rlibperl)
+
+- CPAN Testers Matrix
+
+The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
+
+[http://matrix.cpantesters.org/?dist=App-rlibperl](http://matrix.cpantesters.org/?dist=App-rlibperl)
+
+- CPAN Testers Dependencies
+
+The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
+
+[http://deps.cpantesters.org/?module=App::rlibperl](http://deps.cpantesters.org/?module=App::rlibperl)
+
+## Bugs / Feature Requests
+
+Please report any bugs or feature requests by email to `bug-app-rlibperl at rt.cpan.org`, or through
+the web interface at [http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-rlibperl](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-rlibperl). You will be automatically notified of any
+progress on the request by the system.
+
+## Source Code
+
+
+
+[https://github.com/rwstauner/App-rlibperl](https://github.com/rwstauner/App-rlibperl)
+
+ git clone https://github.com/rwstauner/App-rlibperl.git
+
+# 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.
View
33 README.pod
@@ -1,33 +0,0 @@
-=head1 App::rlibperl
-
-Simplify calling perl with lib directories relative to the installed script
-automatically added to C<@INC> (useful when installed via L<local::lib>):
-
- $HOME/perl5/bin/rlibperl -MSome::Module -e 'do_something'
-
-instead of:
-
- PATH=$HOME/perl5/bin:$PATH perl \
- -I$HOME/perl5/lib/perl5 -MSome::Module -e 'do_something'
-
-Probably most useful as a shebang to call another script
-(without having to write a wrapper script):
-
- #!/home/username/perl5/bin/rbinperl plackup
-
-The equivalent
-
- #!/usr/local/bin/perl -I/home/username/perl5/lib/perl5 -S plackup
-
-doesn't work on linux.
-
-See module POD for more information.
-
-=head1 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.
-
-=cut
Please sign in to comment.
Something went wrong with that request. Please try again.