brian has been a Perl user since 1994. He is founder of the first Perl Users Group, NY.pm, and Perl Mongers, the Perl advocacy organization. He has been teaching Perl through Stonehenge Consulting for the past five years, and has been a featured speaker at The Perl Conference, Perl University, YAPC, COMDEX, and Builder.com.
brian d foy is currently on active duty with the United States Army as a military policeman in Iraq. He says you can e-mail him at firstname.lastname@example.org, if you don't mind waiting a couple months for a reply.
I am in the middle of the Iraqi desert, and I am patching modules, or at least I am trying to. Adam Turoff sent me a CPAN snapshot that is about two weeks old, since snail mail takes that long to get here. I am copying it from the three CDs (that just barely contain it) to my hard drive (which also has just enough room for it) so I can then use it with the cpan program that comes with CPAN.pm, which comes with Perl.
The cpan program is one of the most useful inventions for the Perl programmer. To install almost any module, I simply tell it the name of the module to install, and it downloads and installs it. If that module relies on other modules I do not have, or even newer versions of modules I already have, it takes care of that, too, recursively. If you cannot find the cpan program on your computer, you can cheat with this one-liner that does the same thing:
% perl -MCPAN -e shell
The -M switch tells Perl to use the CPAN.pm module, and the -e switch gives Perl the program on the command line. In this case, shell is a function that CPAN.pm exports. The shell() function simply starts CPAN.pm's interactive shell. When you use it for the first time, it should take you through a configuration process that sets your personal preferences, which show up in the file $HOME/.cpan/CPAN/MyConfig.pm, which CPAN.pm looks at after the site-wide settings in CPAN/Config.pm.
When I was back home enjoying my real life, I had a constantly connected cable modem or a big pipe at work. I configured the cpan program the first time that I used it, when it prompted me and hinted at which values I should use. I never thought of it again. Part of the configuration was a selection of CPAN sites to use for download servers.
Unfortunately, in the desert, I have no network connection, so all of those servers are worthless to me. I do have all of a fairly recent CPAN installed on my laptop, though. I need to configure CPAN.pm to use that rather than anything else.
I start my interactive CPAN.pm session by running the cpan program without arguments:
brian$ cpan cpan shell CPAN exploration and modules installation (v1.63) ReadLine support enabled cpan>
Since I have just started working with Perl again, being busy with other things out here, I have forgotten how a lot of things work. I, like Matthew Broderick in War Games, start by asking for help:
The program displays a plethora of options and commands. I basically know that I want CPAN.pm to look on my computer and not on the network, and that the list of servers is part of the configuration. From the help message, I print the configuration options and settings. I leave out most of the output, and leave in only the settings for the urllist parameter that I want to affect:
cpan> o conf urllist file:///Users/brian/MINICPAN/ http://ftp.sedl.org/pub/mirrors/CPAN/ http://www.perl.com/CPAN/
The first URL in the list is my mini-CPAN repository, created by Randal Schwartz's minicpan program (http://www.stonehenge .com/merlyn/LinuxMag/col42.html). It includes just the latest modules from CPAN and is about one-fifth the size of CPAN. My mini-CPAN, however, is nine months old and does not have the latest versions of the things I want to play with, and rather than use that, I want to use the CPAN snapshot that Adam sent to me.
To change the urllist parameter, which is really just a list, I use Perlish CPAN.pm list commands to change it. In this case, I want to add my local CPAN repository to the front of the list so CPAN.pm checks it first:
cpan> o conf urllist unshift file:///Users/brian/CPAN/
The CPAN.pm module expects the URLs to conform to RFC 1738, although it is a bit liberal in what it actually accepts. To me, this means that my file:// scheme URLs that end with a directory name have a trailing slash.
I check the urllist parameter again to make sure that I added the new URL:
cpan> o conf urllist urllist file:///Users/brian/CPAN/ file:///Users/brian/MINICPAN/ http://ftp.sedl.org/pub/mirrors/CPAN/ http://www.perl.com/CPAN/
When I am satisfied with my changes, I commit the changes to disk and these changes will apply to future interactive sessions. I do not have to do this if I only want to affect the current situation, which I might like to do if I am traveling or at a temporary location.
cpan> o conf commit commit: wrote /Users/brian/.cpan/CPAN/MyConfig.pm
Now, when I use the cpan script, CPAN.pm looks for modules and metadata on my computer rather than the network. I can also use my local CPAN snapshot to update my mini-CPAN, which is much smaller than all of CPAN. The minicpan script uses CPAN.pm to figure out where it should look, and since I just configured CPAN.pm to look on my local computer, that is where minicpan looks.
The Perl Review (http://www.theperlreview.com/at_a_glance .shtml) keeps track of the size of CPAN and the mini-CPAN to measure the Schwartz Factor. As of December 1, that number was 0.2, meaning that the mini-CPAN was about one-fifth the size of the entire CPAN snapshot. Once I update my mini-CPAN, I can get rid of the big snapshot, which is getting close to 2 gigabytes, but then I need to ensure that I get rid of it in my urllist for CPAN.pm. If I keep it in the list, CPAN.pm will try to use that directory before it fails and goes on to the next one in the list, which is slow enough to be annoying.
As before, I use a Perlish command in the CPAN.pm shell. I take off the first item in the list with shift, then check to see that it worked. Once I have it right, I save the changes:
cpan> o conf urllist shift cpan> o conf urllist urllist file:///Users/brian/MINICPAN/ http://ftp.sedl.org/pub/mirrors/CPAN/ http://www.perl.com/CPAN/ cpan> o conf commit commit: wrote /Users/brian/.cpan/CPAN/MyConfig.pm
Now that I have my mini-CPAN updated, and I have CPAN.pm configured to use it, I can install modules as if I were at home and connected to the Internet. I have all the latest versions, and only that in the mini-CPAN, so it does not take up a lot of space on my computer.