NAME

Module::Install::GetProgramLocations - A Module::Install extension that allows the user to interactively specify the location of programs needed by the module to be installed

SYNOPSIS

A simple example:

use inc::Module::Install;
...
my %info = (
  # No default, and can't specify it on the command line
  'diff'     => {},
  # A full path default and a command line variable
  'grep'     => { default => '/usr/bin/grep', argname => 'GREP' },
  # A no-path default and a command line variable
  'gzip'     => { default => 'gzip', argname => 'GZIP' },
);
my %locations = Get_Program_Locations(\%info);

A complex example showing all the bells and whistles:

use inc::Module::Install;
# So Module::Install::GetProgramLocations can be found
use lib 'inc';
# To import Get_GNU_Grep_Version and Get_Solaris_Grep_Version
use Module::Install::GetProgramLocations;
...
my %info = (
  # Either the GNU or the Solaris version
  'grep'     => { default => 'grep', argname => 'GREP',
                  versions => {
                    # Any GNU version higher than 2.1
                    'GNU' =>     { fetch => \&Get_GNU_Grep_Version,
                                   numbers => '[2.1,)', },
                    # Any solaris version higher than 1.0, except 1.1
                    'Solaris' => { fetch => \&Get_Solaris_Grep_Version,
                                   numbers => '[1.0,1.1) (1.1,]', },
                  },
                },
);
my %locations = Get_Program_Locations(\%info);

DESCRIPTION

If you are installing a module that calls external programs, it's best to make sure that those programs are installed and working correctly. This Module::Install extension helps with that process. It allows the user to interactively specify either full path to a program, or an unqualified program name. In the latter case, the module will search the user's path to find the first matching program.

This extension will then perform validation on the program. It makes sure that the program can be run, and will optionally check the version for correctness if the user provides that information.

The extension returns a hash mapping the program names to their absolute paths. (It's best to use the absolute path in order to avoid security problems.)

The user can avoid the interactive prompts by specifying one or more paths to the programs on the command line call to "perl Makefile.PL". Note that no validation of the programs is done in this case.

METHODS

%paths = Get_Program_Locations(\%info)

This function takes as input a hash with information for the programs to be found. The keys are the program names (and can actually be anything). The values are named:

default

The default program. This can be non-absolute, in which case the user's PATH is searched. For example, you might specify "bzip2" as a default for the "bzip" program because bzip2 can unpack older bzip archives.

argname

The command line variable name. For example, if you want the user to be able to set the path to bzip2, you might set this to "BZIP2" so that the user can run "perl Makefile.PL BZIP2=/usr/bin/bzip2".

versions

A hash mapping a descriptive version name to a hash containing a mapping for two keys:

fetch

Specifies a subroutine that takes the program path as an argument, and returns either undef (if the program is not correct) or a version number.

numbers

A string containing allowed version ranges. Ranges are specified using interval notation. That is "[1,2)" indicates versions between 1 and 2, including 1 but not 2. Any characters can separate ranges, although you'd best not use any of "[]()" in order to avoid confusing the module.

This module uses the Sort::Versions module for comparing version numbers. See that module for a summary of version string syntax, and an explanation of how they compare.

The return value for Get_Program_Locations is a hash whose keys are the same as those of %info, and whose values are either an absolute path for the program location, or undef (for no program location).

$boolean = Version_Matches_Range($program_version, $range);

This function takes a program version string and a version ranges specification and determines if the program version is in any of the ranges. For example '1.2.3a' is in the second range of '[1.0,1.1) (1.2.3,)' because 1.2.3a is higher than 1.2.3, but less than infinity.

VERSIONING METHODS

This module provides some functions for extracting the version number from common programs. They are exported by default into the caller's namespace. Feel free to submit new version functions for programs that you use.

$version = Get_GNU_Grep_Version($path_to_program)

Gets the version of GNU grep. Returns undef if the word "GNU" does not appear in the version information

$version = Get_Bzip2_Version($path_to_program)

Gets the version of bzip2.

AUTHOR

David Coppit <david@coppit.org>.

LICENSE

This software is distributed under the terms of the GPL. See the file "LICENSE" for more information.