#!/usr/bin/perl -lan
#
# $Id: module-install.pl,v 1.10 2003/01/13 05:28:42 jmates Exp $
#
# Copyright (c) 2001-2002, Jeremy Mates.  This script is free
# software; you can redistribute it and/or modify it under the same
# terms as Perl itself.
#
# Run perldoc(1) on this file for additional documentation.

BEGIN {
    use CPAN;			# perl interface to CPAN site

    # what shell to use for "get" installs
    $shell = ($ENV{SHELL} ? $ENV{SHELL} : "/bin/sh");
}

# skip commented or blank lines
next if $F[0] =~ /^#/;
next if $F[0] =~ /^\s*$/;

# latest CPAN module has "expandany" which avoids having to muck
# around manually with the expand function; however, not everyone has
# the latest CPAN...
$type = 'Module';		# default

$type = 'Bundle' if $F[0] =~ /^Bundle/;
$type = 'Distribution' if $F[0] =~ m:/:;

$o = CPAN::Shell->expand($type, $F[0]);

die "Problem expanding $F[0]" unless defined $o;

if ($F[1] =~ /get/) {
	# drop to shell, let user manually install
	$o->get;

	print "Droping to shell to allow manual install of $F[0]";
	print "Exit out of shell to continue script.";

	system $shell;
} else {
	# regular install
	$o->force if $F[1] =~ /force/;
	$o->install;
}

__END__

=head1 NAME

module-install.pl - to mass install CPAN modules

=head1 SYNOPSIS

Read a list of modules from a file and attempt to install them:

  $ module-install.pl perl-modules

=head1 DESCRIPTION

=head2 Overview

This script eases the task of installing large numbers of perl modules
off of CPAN.  The main use is to automate the installation of the
often large number of additional modules needed by machines that use
perl extensively.

The script reads a list of Modules, Bundles, or Distributions
(C<perldoc CPAN> for a discussion of these terms) and attempts to
install them.  Input lines beginning with the pound character are
skipped, and empty lines are ignored.  Optionally, the word "force"
can be specified following the item to be installed, which will cause
CPAN to attempt to install the module regardless of the C<make test>
status.  Modules are installed in the order in which they are listed,
so modules with dependancies should be listed after modules they
depend on.

In a perfect world, all modules would install without hitch on every
OS.  Until that day, there is the "get" option, similar to force, that
will download and unpack the module in question into the CPAN build
directory, and then drop to a sub-shell in which you are intended to
manually install the module in question.  This is for modules that
otherwise refuse to install right, or require special Makefile.PL
arguments that CPAN cannot handle.

Example input data:

  # install these first
  MIME::Base64
  URI

  # drop to shell after downloading this one
  Net::Cmd      get

  # 'make test' hits external websites, so force install
  Net::SSLeay   force

  # install this specific version of CGI ("Distribution" in 
  # CPAN terms)
  L/LD/LDS/CGI.pm-2.77.tar.gz

  # Bundles are supported, too
  Bundle::Net::LDAP

Distribution names probably should not be used, as they tie the data
to a specific file, which could go away in the future.  Support for
them is intended for the situation where the most up-to-date version
of the module is either broken, or does not work on the version of
perl you are running.

Beware the tendancy of CPAN to upgrade perl for you; I believe the
problem stems from Data::Dumper (part of stock perl) being listed as a
requirement for Bundle::libnet, which is part of Bundle::CPAN, which
CPAN advises you to install once you set it up.

A work around is to use the 'b' command in the CPAN shell to list
Bundle module requirements, and list the required modules (minus any
that are part of perl) in your module-list file passed to this script.

  $ perl -MCPAN -e'CPAN::Shell->b("Bundle::CPAN")' | grep CONTAINS

  $ perl -MCPAN -e'CPAN::Shell->b("Bundle::libnet")' | grep CONTAINS

=head2 Normal Usage

  $ module-install.pl module-list

The typical usage will be to specify a list of perl modules in a text
file, and read that file as a command line argument.  The modules can
also be specified on STDIN:

  $ (echo CGI; echo "Net::SSLeay force") | module-install.pl

=head1 EXAMPLES

Sample module lists that the author uses and commentary on why CPAN
does what it does should be available under:

http://sial.org/code/perl/docs/

=head1 BUGS

=head2 Reporting Bugs

Newer versions of this script may be available from:

http://sial.org/code/perl/

If the bug is in the latest version, send a report to the author.
Patches that fix problems or add new features are welcome.

=head2 Known Issues

No known bugs.

=head1 SEE ALSO

CPAN(3), perl(1), http://www.cpan.org/

=head1 AUTHOR

Jeremy Mates, http://sial.org/contact/

=head1 COPYRIGHT

Copyright (c) 2001-2002, Jeremy Mates.  This script is free
software; you can redistribute it and/or modify it under the same
terms as Perl itself.

=head1 VERSION

  $Id: module-install.pl,v 1.10 2003/01/13 05:28:42 jmates Exp $

=cut