NAME

App::Dispatch - Tool to have #! dispatch to the best executable for the job.

DESCRIPTION

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 perl. A result of this is heavy use of #!/usr/bin/env to lookup the correct binary to execute based on your $PATH. Sometimes though you cannot control your environment as well as you would like. You cannot always be sure that the binary in $PATH is the one you want.

App::Dispatch solves the same problem as /usr/bin/env, but in a way that gives you more control. With App::Dispatch you put a configuration file in /etc (and optionally your home directory) which allows you provide aliases to specific binaries. In your #! line you specify which program, and a cascade of aliases to try. If the alias(es) you do not want are missing, or the program is missing altogether, it will result in an error.

App::Dispatch also has 2 special aliases 'SYSTEM' which should be used to specify which binary is used by the system, and 'DEFAULT' which should be used when none is specified. In this way you can have system tools with a #! line that is very clear on which binary should run it.

SYNOPSYS

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 exodist7@gmail.com

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.