NAME
App::Dispatch - Tool to have #! dispatch to the best executable for the
job.
DESCRIPTION
App::Dispatch is an alternative to "/usr/bin/env". Unlike
"/usr/bin/env", it does not rely on your environment to tell it which
program to use. You can set system-wide, and user level configurations
for which program to use. You can also specify a cascade of aliases
and/or paths to search.
Lately it has been a trend to avoid the system install of programming
languages, Perl, Ruby, Python, etc, in most cases it is recommended that
you do not use the system installation of the language. A result of this
is heavy use of "#!/usr/bin/env" to lookup the correct binary to execute
based on your $PATH. The problem with "/usr/bin/env" is that you may not
always have control over the environment. For example if you have a
script that you must run with sudo, your $PATH will be reset.
With App::Dispatch you can specify multiple locations to try when
looking for the program. You can also configure aliases at the system or
user level. This is useful when you have multiple versions of the
program installed and wish different things to use different ones by a
label. In this way the versions need not be in the same location on each
machine that can run the script.
SYNOPSYS
NO CONFIG
The following #! line will cause the script to be run by perl, it will
try each path listed in order.
#!/usr/local/bin/dispatch perl /path/to/perl /alternate/path/to/perl /another/perl
This tells the script to use the specified path if available, otherwise
fall back to whichever perl is in the environment.
#!/usr/local/bin/dispatch perl /path/to/perl ENV
You can also pass arguments to the program by putting them after "--":
#!/usr/local/bin/dispatch perl /path/to/perl ENV -- -w
WITH CONFIG
$HOME/.dispatch.conf:
[perl]
SYSTEM = /usr/bin/perl
DEFAULT = /opt/ACME/current/bin/perl
production = /opt/ACME/stable/bin/perl
This #! line will run perl, it will find the 'production' perl, if no
production perl is found it will try 'DEFAULT'. Anything after the -- is
passed as arguments to perl.
#!/usr/local/bin/dispatch perl production DEFAULT -- -w
This will run the default perl.
#!/usr/local/bin/dispatch perl
CONFIG FILES
LOCATIONS
Locations are loaded in this order. All locations that exist are loaded.
Later files can override earlier ones.
/etc/dispatch.conf
The system wide configuration
/etc/dispatch/*
System wide config dir, to have app specific config files for easier
management with system packages.
$HOME/.dispatch.conf
User specific overrides or additions.
EXAMPLE
[perl]
SYSTEM = /usr/bin/perl
DEFAULT = /opt/ACME/current/bin/perl
production = /opt/ACME/stable/bin/perl
[gcc]
SYSTEM = /usr/bin/gcc
DEFAULT = /usr/bin/gcc
old = /opt/legacy/bin/gcc
NOTE FOR CPAN AUTHORS
This tool is very useful for perl shops in their own scripts. However it
most likely should not be used in any scripts that will be installed
with a cpan distribution. Distributions should use a normal #! line that
will be rewritten by the build tools to use the perl for which the dist
was installed. This is important because of dependency chains and XS
modules.
AUTHORS
Chad Granum
[email protected]
COPYRIGHT
Copyright (C) 2013 Chad Granum
App-Dispatch is free software; Standard perl licence.
App-Dispatch is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
more details.
