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. This page links to documentation on the usage of CPAN; consult the parent page for related documentation.
Using CPAN to maintain a module tree in a custom location is documented elsewhere.
Invocation
The latest versions of CPAN install a cpan command somewhere on the system. With an up to date version of CPAN, the following sets of commands are equivalent. Hereafter, the shorter cpan method will be used:
# enter the CPAN shell
# perl -MCPAN -e shell
# cpan
# install the Acme::Bleach module
# perl -MCPAN -e install Acme::Bleach
# cpan -i Acme::Bleach
Depending on the shell, one may need to issue the hash -r or rehash command to make the new cpan command appear in the search path after the latest CPAN is installed.
Case Sensitive Searches
The i /SEARCH/ command will search without case sensitivity. To perform a case sensitive search, disable the default case insensitivity via i /(?-i)SEARCH/. This and other regular expression options are detailed in perlre.
Install a Specific Module Version
The CPAN documentation covers how to install a specific module version. This is done by installing the specific distribution file for the module version, as opposed to whatever current module version CPAN happens to find at the time:
$ cpan
cpan> i /Term::CallEditor/
…
Module id = Term::CallEditor
CPAN_USERID JMATES (Jeremy Mates <jmates@sial.org>)
CPAN_VERSION 0.11
CPAN_FILE J/JM/JMATES/Term-CallEditor-0.11.tar.gz
INST_FILE (not installed)
cpan> install J/JM/JMATES/Term-CallEditor-0.11.tar.gz
Running make for J/JM/JMATES/Term-CallEditor-0.11.tar.gz
…
Note that the author could delete a specific module version at any time. Therefore, do not rely on specific module versions being available on CPAN over time (though old versions of the module may be available on backpan). If specific module versions are required, archive these into a local software depot or vendor package system.
autobundle
The CPAN autobundle can be used to ease perl upgrades, by creating a special bundle containing all the installed modules of the current version of perl. This bundle can then be installed once the new version of perl is installed.
cpan> autobundle
…
Wrote bundle file
/var/spool/cpan/Bundle/Snapshot_2003_10_01_00.pm
cpan> quit
# upgrade perl here …
# cpan
cpan> install Bundle::Snapshot_2003_10_01_00
Autobundle appears to install the modules in alphabetical order; setting the prerequisites_policy policy to ask should help. Multiple install runs may be needed to install everything properly. Module build failures will lead to much recursion on the part of CPAN.
Install Dependent Modules
Automatic installation of dependent modules is configured via the prerequisites_policy configuration option, though also enabling the PERL_MM_USE_DEFAULT shell environment variable should help avoid interactive questions:
cpan> o conf prerequisites_policy follow
cpan> o conf commit
$ export PERL_MM_USE_DEFAULT=1
$ cpan -i …
However, some modules may not honor the PERL_MM_USE_DEFAULT environment variable, so may still prompt during the installation process. Also, failed module builds will derail the install; do not force install a module should any of the dependent module builds have failed. Investigate why the dependent modules failed first.
Old Modules
Some modules found by CPAN are out of date, and will not compile. An updated module may be available on CPAN, just not linked to as “current” by CPAN. Modules known to have this problem include the following. The links below should point to the current version of the modules.
Manual Build
On occasion one may need to manually build or test a module, or consult the module directory to read the documentation on any special needs the module may have. This can be done with the CPAN shell look command.
cpan> look Net::SSLeay
…
Working directory is /var/spool/cpan/build/Net_SSLeay.pm-1.25
# exit
cpan>
sudo
If CPAN is installed in your home directory, the system-wide cpan may cause problems when run via sudo(8), as by default sudo will invoke CPAN using the ~/.cpan/CPAN/MyConfig.pm configuration, but as root, which causes no end of trouble. To avoid this problem, reset the HOME environment variable with the -H option to sudo when invoking CPAN:
$ sudo -H cpan
Uninstall
See uninstalling Perl modules. Usually a bad idea and a waste of time.
Upgrading
How to upgrade all the modules on the system like apt-get is documented in the CPAN manual. This may be a mistake, depending on how critical the system is, and what test suites are available to confirm that the new modules have not broken anything, assuming everything compiles and builds properly:
# install everything that is outdated on my disk (probably a Bad Idea™):
# perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
Before you run this, ask again: are you really sure you need to upgrade the modules? What bug is being fixed? How will you rollback if something breaks after the update?
