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 %location_info = get_program_locations(\%info);

  print "grep path is " . $location_info{'grep'}{'path'} . "\n";

A complex example showing all the bells and whistles:

  use inc::Module::Install;
  ...
  # User-defined get version program
  sub get_solaris_grep_version
  {
    my $program = shift;

    my $result = `strings $program | $program SUNW_OST_OSCMD`;

    return undef unless $result =~ /SUNW_OST_OSCMD/;

    # Solaris grep isn't versioned, so we'll just return 0 for it
    return 0;
  }

  my %info = (
    # Either the GNU or the Solaris version
    'grep'     => { default => 'grep', argname => 'GREP',
                    type => {
                      # Any GNU version higher than 2.1
                      'GNU' =>     { fetch => \&get_gnu_version,
                                     numbers => '[2.1,)', },
                      # Any solaris version
                      'Solaris' => { fetch => \&get_solaris_grep_version,
                                     numbers => '[0,)', },
                    },
                  },
  );

  my %location_info = get_program_locations(\%info);

  print "grep path is " . $location_info{'grep'}{'path'} . "\n";
  print "grep type is " . $location_info{'grep'}{'type'} . "\n";
  print "grep version is " . $location_info{'grep'}{'version'} . "\n";

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. Given a specification of the required programs, it attempts to find a working version on the system based on the Perl configuration and the user's path. The extension then returns a hash mapping the program names to a hash containing the absolute path to the program, the type, and the version number. (It's best to use the absolute path in order to avoid security problems.)

The program specification allows the user to specify a default program, a command-line name for the program to be set, and multiple types of satisfying implementations of the program. For the types, the user can specify a function to extract the version, and a version range to check the version.

The extension defaults to interactive mode, where it asks the user to specify the paths to the programs. If the user specifies a relative path, the extension converts this to an absolute path. The user can specify "none", in which case the hash values will be undefined. Similarly, if the , or if the type or version cannot be determined, then the hash values will be undefined.

The extension also supports a noninteractive mode, where the programs are provided on the command line. For example, "perl Makefile.PL PROGRAM=<program>" is used on the command line to indicate the desired program. The path is converted to an absolute path. "<program>" can be empty to indicate that it is not available.

This extension will perform validation on the program, whether or not it was specified interactively. It makes sure that the program can be run, and will optionally check the version for correctness if the user provides that information. If the program can't be run or is the wrong version, an error message is displayed. In interactive mode, the user is prompted again. If the user enters the same information twice, then the information is used regardless of any problems. In noninteractive mode, the program is used anyway.

METHODS

get_program_locations(<HASH REF>)

This function takes as input a hash with information for the programs to be found, and returns a hash representing program location data. The keys of the argument hash 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".

types

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.

Each of your fetch routines should only succeed for one kind of implementation, returning undef when they fail.

The return value for get_program_locations is a hash whose keys are the same as those of %info, and whose values are hashes having three values:

path

The absolute path to the program. This value is undef if the user chose no program.

type

The name of the type, if there are multiple possible types. This name corresponds to the name originally given in the "types" hash. This value is undef if no program was chosen by the user, or if there was no types hash value.

version

The version number of the program.

version_matches_range(<PROGRAM VERSION>, <RANGE>);

This function takes a program version string and a version ranges specification and returns true 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_version(<PATH TO PROGRAM>)

Gets the version of a general GNU program. Returns undef if the application does not appear to be a GNU application. This function relies on certain conventions that the Free Software Foundation uses for printing the version of GNU applications. It may not work for all programs.

$version = get_bzip2_version($path_to_program)

Gets the version of bzip2.

LICENSE

This code is distributed under the GNU General Public License (GPL) Version 2. See the file LICENSE in the distribution for details.

AUTHOR

David Coppit <david@coppit.org>

SEE ALSO

Module::Install