Don't CPANic

Joseph N. Hall is the author of Effective Perl Programming (Addison-Wesley, 1998). He teaches Perl classes, consults, and plays a lot of golf in his spare time.



In my previous article on the Perl CPAN module (April 1999), I talked about what it does and how you can use it to help automate the process of installing and maintaining Perl modules. In this column I'll cover a few more of the CPAN module's features and show you how to use it to help accomplish some more complicated tasks.

What's Up to Date?

The CPAN shell has a useful command called r, which presents you with a list of modules that are apparently not up to date. You can use it with an argument:

% perl -MCPAN -e shell
cpan shell — CPAN exploration and modules installation (v1.50)
ReadLine support enabled
cpan> r URI
CPAN: LWP::UserAgent loaded ok
Fetching with LWP:
(output deleted here)

Package namespace installed latest in CPAN file
URI 1.00 1.04 GAAS/URI-1.04.tar.gz

Or just use it without an argument, in which case it will present you with a list of all modules that need updating. You can also do this from the command line:

% perl -MCPAN -e 'CPAN::Shell->r'

You have to use Perl method call syntax here—you can't just say

% perl -MCPAN -e r

because only certain shell functions (e.g., install, test) are exported by CPAN, and r isn't one of them.

Reinstalling Modules That Are Out of Date

To reinstall modules that are out of date, you need to do a little programming. The methods (like r) that produce lists of modules when used in the CPAN shell return Perl lists when used in a program. You could, for example, just list them:

use CPAN;
my @modules = CPAN::Shell->r;
print "The following modules need updating:\n";
for (@modules) { print STDOUT " $_\n" }

If you run this program you'll see that it still produces the usual stream of messages like:

Scanning cache /home/joseph/.cpan/build for sizes
Fetching with LWP:
 ftp://ftp.cdrom.com/pub/perl/CPAN/modules/03modlist.data.gz

If you want to suppress these messages, there are ways to do that. You may not want to suppress them, however, in the case of modules that have dependencies on other modules, because the resulting stream of half-there, half-not-there messages can be pretty confusing. CPAN.pm's output is filtered, for the most part, through a bottleneck routine called CPAN::Frontend::myprint, which in turn is normally delegated to CPAN::Shell::myprint. To quiet things down you'll need to change this. You could just patch CPAN::Shell::myprint, replacing it with a subroutine that does nothing:

use CPAN;
BEGIN { local $^W; *CPAN::Shell::myprint = sub { 1 } }

Redefining a subroutine generates a warning, thus the local $^W to turn off warnings within the BEGIN block.

A more civilized way is to create your own subclass of CPAN::Shell and override myprint there. This is easier than it sounds:

use CPAN;
BEGIN {
 @MyFrontend::ISA = 'CPAN::Shell';
 sub MyFrontend::myprint { 1 }
 $CPAN::Frontend = 'MyFrontend';
}

Here we've made MyFrontend a subclass of CPAN::Shell, defined a new myprint, and set CPAN::Frontend to MyFrontend rather than its usual value of CPAN::Shell.

Of course, you may want to see the output from CPAN::Shell anyway, in which case you can ignore the preceding discussion.

Anyway, with that out of the way, we can now write a short program to automatically update out-of-date modules. Suppose we'd like to do all the Math:: modules:

my @modules = CPAN::Shell->r('/^Math::/');
for (@modules) {
 print STDOUT "Reinstalling $_\n";
 CPAN::Shell->install($_);
}

You could even do this more succinctly:

CPAN::Shell->install(CPAN::Shell->r('/^Math::/'));

Problems with Auto-Reinstalling

When a module depends on one or more other modules, CPAN.pm tracks those dependencies and tries to install updated versions of those modules beforehand, recursing through multiple levels of dependencies if necessary. Many popular distributions such as LWP (libwww-perl) have several dependencies. If you are writing programs to automatically reinstall updated versions of modules, you should probably have CPAN automatically reinstall any modules that they depend on. The easiest way to do this is to set the "prerequisites_policy" configuration variable in CPAN to "follow":

% perl -MCPAN -e shell
cpan> o conf prerequisites_policy follow
 prerequisites_policy follow
cpan> o conf commit
commit: wrote /home/joseph/.cpan/CPAN/MyConfig.pm

Now CPAN.pm will automatically find and (re)install any modules that the modules you are reinstalling require. Other possible values of the policy are "ignore," which is risky because failing to install updated versions of required dependencies will eventually result in a Perl install that doesn't work properly, and "ask," which isn't all that useful unless you are running CPAN.pm interactively.

Some modules are a bit resistant to automatic installation. Some modules have interactive aspects to their install procedure (like libnet and Term::ReadLine). Other modules just have very complex install procedures that don't always go smoothly (like Tk or Image::Magick). I don't have any advice that will magically resolve this problem for you—you'll just have to deal with those ornery modules as you encounter them.

If you run some kind of auto-update as a cron job, you will want to consider the consequences of failed installs, as well as what happens when you successfully install a module that is either buggy or no longer compatible with your current Perl programs. Sooner or later it will happen. Obviously you should never automatically update a Perl configuration on a "production" platform. But if you want to just keep up with the latest and greatest on your own machine, or set up a machine specifically for the purpose of debugging software against the latest and greatest Perl modules, then you will certainly want to consider using CPAN.pm to automate the updating process.

(Auto)bundling for Fun and Profit

Let's suppose that you have just taken over operation of a Perl installation and you have been asked to help move it to another server. In general, you can't just copy a Perl installation from one machine to another. You have to reinstall Perl and then reinstall all the modules that were present in the original installation. But how do you find out what modules were there?

The answer is found in the CPAN module, of course. The CPAN shell has a command called autobundle, which creates a list (called a "bundle") of all of the modules that are installed in the directories in your Perl include path (in @INC). Creating an autobundle is easy:

% perl -MCPAN -e shell
cpan> autobundle

(copious output follows)

Wrote bundle file
 /home/joseph/.cpan/Bundle/Snapshot_1999_10_05_00.pm

If you look in the bundle file you'll see that it's actually a specially formatted Perl module. You can look at it with perldoc (expect some warnings from the always-pedantic pod2man translator):

% perldoc /home/joseph/.cpan/Bundle/Snapshot_1999_10_05_00.pm

The bundle's main use, however, is that it gives you a way to automatically install a "bundle" of modules. All you have to do is return to the CPAN shell and type:

cpan> install Bundle::Snapshot_1999_10_05_00

The CPAN module will go through the list of modules in the autobundle and automatically reinstall them. You can even do it right from the command line:

% perl -MCPAN -e 'install Bundle::Snapshot_1999_10_05_00'

You can use the autobundle to "copy" a Perl installation from one site to another. Create an autobundle on one machine, move it to the next, and execute the install. Voilà—you now have a new install with the latest versions of those modules in place.

The only problem with autobundles is that the modules in the bundle file appear in alphabetical order. This isn't generally the most convenient order. As I noted above, a few modules require interactive installation. It's best to identify these and relocate them to the top of the bundle file so that you can deal with the interactive installs all at once. You may also want to break the bundle file into pieces ("interactive" and "noninteractive," perhaps), or just exclude the more troublesome modules from the bundle altogether.

Summary and Acknowledgments

That's it for my coverage of the CPAN module—for now, anyway. Perhaps some of the ideas here will help you administer your Perl installation more quickly and effectively.

One final note: I'd like to thank Andreas Koenig for his years of excellent work on the CPAN module, and also the members of Perl 5 Porters who defined and standardized CPAN and the Perl module structure. Without their efforts, most of the power and diversity available in Perl modules today simply wouldn't exist.