# installs a single module from CPAN, following dependencies
sub install_module {
    my ($name, $req_version) = @_;

    # push onto the queue.  This keeps everything simpler below
    CPAN::Queue->new($name);

    # process the queue
    while (my $q = CPAN::Queue->first) {
	# get a module object one way or another
	my $m = ref $q ? $q : CPAN::Shell->expandany($q);
	hard_fail(<<END) unless $m;
Couldn't find $q on CPAN.  Your CPAN.pm installation 
may be broken.  To debug manually, run:

  perl -MCPAN -e 'install $q'
END

	print "Found ", $m->id, ".  Installing...\n";

	# need to force?
	my $key = $m->isa('CPAN::Distribution') ? $m->called_for : $m->id;
	$m->force('install') if $flags{$key} and $flags{$key} & FORCE;

	# need PG env vars?
	if ($flags{$key} and $flags{$key} & PG_ENV) {
	    $ENV{POSTGRES_INCLUDE} = $PG->{include_dir};
	    $ENV{POSTGRES_LIB}     = $PG->{lib_dir};
	}
	    
	# do the install.  If prereqs are found they'll get put on the
	# Queue and processed in turn.
	$m->install;

	# I don't understand why this is necessary but CPAN.pm does it
	# when it walks the queue and not doing it results in failures
	# in some modules installs (SOAP::Lite, MIME::Lite).
	$m->undelay;

	# remove self from the queue
	CPAN::Queue->delete_first($q);
    }

    # check to make sure it worked
    print "Checking $name installation...\n";
    # try loading the module
    eval "require $name";
    hard_fail(<<END) if $@;
Installation of $name failed.  Your CPAN.pm installation 
may be broken.  To debug manually, run (as root):

  perl -MCPAN -e shell

Then at the "cpan>" prompt:

  look $name

You can then attempt to install the module manually with:

  perl Makefile.PL
  make test
  make install

END

    if (defined $req_version) {
	eval { $name->VERSION($req_version) };
	hard_fail(<<END) if $@;
Installation of $name version $req_version failed.  Your 
CPAN.pm installation may be broken.  To debug manually, 
run (as root):

  perl -MCPAN -e shell

Then at the "cpan>" prompt:

  look $name

You can then attempt to install the module manually with:

  perl Makefile.PL
  make test
  make install

END
    }
    
    # all done.
    print "$name installed successfully.\n";
}