Life with CPAN

The Comprehensive Perl Archive Network (CPAN) hosts Perl modules and scripts. The CPAN module provides an interface to query and install modules hosted on CPAN. These pages document the setup and usage of CPAN, with attention to common tasks and pitfalls along the way.

Perl modules used in production must be saved locally, either under version control, a package system, or software depot. Doing so ensures the modules can be installed on new systems, or rebuilt on new platforms. This supports reproducible module installs over time, as CPAN modules may change or be removed without warning.

Use CPAN::Reporter to submit module test results. Try SmokeAuto for automated module testing.

Alternatives

Other means of installing perl modules from CPAN include the following, which are not discussed in detail here.

• CPANPLUS. “CPAN++ (also referred to and pronounced as CPANPLUS) is a new and flexible method of perl module management and installation using the CPAN. It aims to be a rewrite, and in time a replacement to the current CPAN module. In addition to fixing some long-standing problems, CPAN++ includes new features, such as module uninstall.”
   
• PAR - Cross-Platform Packaging and Deployment tool.
   
• Perl Package Manager (PPM) - Included with ActiveState Perl.
   
• Other. Some vendors make perl modules available via other methods, such as ActiveState’s PPM, the FreeBSD ports system, or similar package software. On Mac OS X, install XCode, or use on of the various package systems available. These offer tight integration with the system in question, but may include outdated modules or use different naming conventions and filesystem layouts.

For example, p5-libwww is the FreeBSD port of the module distribution libwww-perl on CPAN, and LWP::UserAgent a module found in that distribution. The following commands are equivalent means to install libwww-perl via the FreeBSD ports system, yum on RedHat systems, or the cpan command included with modern versions of CPAN.

# portinstall p5-libwww
# yum -y install perl-libwww-perl
# cpan -i LWP::UserAgent

To lookup the documentation for a module, use http://search.cpan.org/perldoc/Module::Name. The documentation should also show the distribution a module belongs to, for example Data::Dumper. Other search interfaces include the CPAN Search Site or the CPAN shell search features.

• Conversion scripts. cpan2rpm helps convert Perl modules into RedHat Package Manager (RPM) files. The resulting *.rpm packages can be installed via a local Yellowdog Updater, Modified (YUM) server. On Debian, try dh-make-perl --install --cpan Module::Name or cpan2dist: Packaging CPAN Modules for Debian.

perl Upgrade Bug

The first time CPAN is invoked, it will run through a set of questions, such as which CPAN mirror site to use. Following the questions, CPAN may recommend that you install Bundle::CPAN or Bundle::libnet. Avoid installing these bundles!

Older versions of CPAN have a bug whereby a new version of perl itself may be installed. To avoid this problem, install the latest version of CPAN first:

# perl -MCPAN -e '$ENV{FTP_PASSIVE} = 1; install CPAN'

Setting the FTP_PASSIVE=1 environment variable avoids another common problem where active File Transfer Protocol (FTP) connections are blocked by a local firewall (see below).

If already in the CPAN shell following the preferences questions, use:

cpan> install CPAN

For reference, the bug is that Bundle::CPAN or Bundle::libnet may list Data::Dumper as a dependency. Data::Dumper is a built-in perl module, so when old versions of CPAN lookup Data::Dumper, they find a new version of perl to install. This bug has been fixed in current versions of CPAN.

Active FTP versus Firewalls

Network problems may prevent access to CPAN mirror sites. The chief problem will be utilities set to use active FTP, which most firewalls block. Peruse Active FTP vs. Passive FTP, a Definitive Explanation for more details. I recommend enabling passive FTP by default, though this setting will need to be done for a variety of utilities CPAN might run, such as wget or Net::FTP. Alternatives include disabling the client firewall to allow active FTP connections back from the FTP server, or configuring a local FTP proxy.

Set the FTP_PASSIVE environment variable before running cpan.

# env FTP_PASSIVE=1 cpan -i Net::FTP

During the install of the libnet distribution, enable passive FTP.

…
Ah, I see you already have installed libnet before.

Do you want to modify/update your configuration (y|n) ? [no] y
…
Should all FTP connections be passive (y|n) ? [no] y

If Net::FTP is already installed, edit the libnet.cfg configuration file to use passive FTP.

$ perl -le 'for (@INC) { $_ .= "/".$ARGV[0]; print if -f }' Net/libnet.cfg
/usr/local/lib/perl5/5.8.1/Net/libnet.cfg
$ grep passive /usr/local/lib/perl5/5.8.1/Net/libnet.cfg
'ftp_int_passive' => 1,

If Net::FTP does not work, or certain utilities take too long to time out, consider the following options.

• Disable Net::FTP.

If Net::FTP does not work, try adding the following line to the CPAN/Config.pm preferences file. More information on dontload_hash posted to the perl.perl5.porters newsgroup. Also consider installing LWP::UserAgent, which is more capable than Net::FTP.

'dontload_hash' => { 'Net::FTP' => 1 },

• Disable utilities that do not work

To reconfigure CPAN to not call certain utilities, replace the path to the utility with a single space.

$ grep ncftp ~/.cpan/CPAN/MyConfig.pm
'ncftp' => q[ ],
'ncftpget' => q[ ],

Preferences Questions

CPAN will ask for preferences settings any time the Config.pm preferences file does not exist or is out of date. The default choice should be acceptable for most.

• CPAN build and cache directory? [/root/.cpan]

I use /var/spool/cpan, as the root filesystem tends to be small on my systems, and the spool area makes more sense to me.

• Policy on building prerequisites (follow, ask or ignore)? [ask]

Leave this setting set to ask when upgrading CPAN the first time, to prevent dependency lookups automatically installing the latest stable perl. With ask set, one can say no to queries that ask to install Bundle::CPAN, Bundle::libnet, or Data::Dumper until the latest version of CPAN is installed.

• Where is your * program? [*]

This series of questions lets one configure (or disable) paths to various utilities CPAN may use to download or unpack modules. It is safe to leave entries blank, as long as CPAN is left with at least one working program that can download modules and another to expand them.

To disable a particular utility, use a single space instead of a file path.

• Parameters for the 'make install' command?

Set this option to include UNINST=1 if installing as root. This properly cleans out files from older versions of a module being installed. For user-specific setup, I never set the UNINST option, to avoid remove warnings of unremovable system files.

• Now we need to know where your favorite CPAN sites are located.

Choose several CPAN mirror sites. Use traceroute or bandwidth testing tools to determine which mirrors are best for your system. Or, mirror CPAN to a local system.

The mirrors list may need to be updated periodically, if a previous mirror site stops hosting CPAN. Symptoms of this will be slow downloads as CPAN fails though the mirror list.

Reconfiguring CPAN

To alter the CPAN preferences, either edit the Config.pm configuration file manually, or use the o conf command in the CPAN shell.

cpan> o conf init

The init configuration option runs through all the configuration questions, which may be time consuming. For example, other o conf commands can be used to list, remove, and add mirror sites, and then to save the changes to disk.

cpan> o conf urllist
urllist
ftp://ftp.kernel.org/pub/CPAN/
Type 'o conf' to view configuration edit options


cpan> o conf urllist shift

cpan> o conf urllist push ftp://ftp-mirror.internap.com/pub/CPAN/

cpan> o conf urllist
urllist
ftp://ftp-mirror.internap.com/pub/CPAN/
Type 'o conf' to view configuration edit options


cpan> o conf commit
commit: wrote /usr/local/lib/perl5/5.6.1/CPAN/Config.pm

To manually edit the existing configuration file, either open the user-specific ~/.cpan/CPAN/MyConfig.pm directly, or locate the system-wide configuration file and edit that:

$ perl -le 'for (@INC) { $_ .= $ARGV[0]; print if -f }' /CPAN/Config.pm
/System/Library/Perl/CPAN/Config.pm

Critical configuration changes should be managed by configuration management and not random manual edits.

Usage Tips

Once the latest version of CPAN has been installed, it is safe to install Bundle::CPAN (as older versions of CPAN would attempt to upgrade perl itself). If already in the CPAN shell, run reload cpan first.

cpan> reload cpan
…
cpan> install Bundle::CPAN

Consult the usage tips documentation for more information, such as how to perform case sensitive searches, install specific module versions, and more.

Debugging Module Build Problems

See the Debugging CPAN Build Problems guide for more information.

Using CPAN with a non-root account

Notes on using CPAN with a non-root account, or installing Perl modules to directories besides the default system areas, such as a software depot or a personal module tree under $HOME. Consider also local::lib to bootstrap custom Perl module installation directories.

Mac OS X

Problems with CPAN on Mac OS X. These notes pertain mostly to older releases of Mac OS X: the various bugs exposed by the differences of OS X from traditional Unix systems (notably regarding file system case sensitivity) have largely been patched in either the affected Perl modules, or addressed somehow by Apple.