The Comprehensive Perl Archive Network (CPAN) hosts Perl distributions. The CPAN module provides an interface to query and install modules hosted on CPAN. Other interfaces are available, such as the CPAN webpage, or App::cpanminus.
Perl distributions (example: libnet) contain one or more module files, plus other metadata files, unit tests, and more. The module files are often arranged in a hierarchy, though this arrangement is left to the author: the module Acme::Foo and the module Acme::Foo::Bar could belong to two different distributions that have nothing to do with one another. Various conventions keep the Perl authors in line, though there is no formal organization.
Perl modules (example: Net::FTP, part of the libnet distribution) are usually pure Perl. Some modules however contain XS code; these require a C development environment to compile, plus various C libraries. Check the vendor ports or package system, or compile by hand, depending. Some modules have additional requirements. DBD::Pg requires both the Postgres development environment to compile against and a Postgres database to connect to. Perl module names are Case Sensitive.
perl searches @INC for modules. Net::FTP is stored as Net/FTP.pm on a Unix filesystem, and the first matching entry in @INC will be used. @INC can be adjusted in a variety of ways.
$ perl -E 'say for grep { -f "$_/Net/FTP.pm" } @INC'
/System/Library/Perl/5.10.0
$ file /System/Library/Perl/5.10.0/Net/FTP.pm
/System/Library/Perl/5.10.0/Net/FTP.pm: Perl5 module source text
Interfaces to CPAN
Various software exists to install Perl distributions from CPAN. CPAN is the traditional interface; systems with limited resources will benefit from the simplicity of App::cpanminus. Perl modules are ideally organized into a custom library directory; local::lib provides an easy method of creating arbitrary library directories for any user.
- CPAN - traditional interface. Current versions ship with a cpan command. If not yet configured, CPAN asks too many questions; the defaults suffice, and really only the mirrors to use need be filled in (CPAN caches the list of mirrors in ~/.cpan/sources/MIRRORED.BY for reference). If possible, use a HTTP mirror, or set the FTP_PASSIVE=1 environment variable.
- CPANPLUS. “CPAN++ (also referred to and pronounced as CPANPLUS) is a 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.”
- App::cpanminus - simple, lightweight installer. To reduce the memory footprint of CPAN, consider CPAN::SQLite.
# install by module name
$ cpan File::AtomicWrite
…
# or by distribution name (not recommended)
$ cpan JMATES/File-AtomicWrite-1.03.tar.gz
…
# check that the module can now be found in @INC
$ perl -MFile::AtomicWrite -e 42
$ perl -MFile::AtomicWrite -le 'print $INC{"File/AtomicWrite.pm"}'
/Library/Perl/5.10.0/File/AtomicWrite.pm
Various software exists to help organize or package Perl modules for reuse elsewhere. These can be used in conjunction with an installer:
- PAR - Cross-Platform Packaging and Deployment tool. This might be used after one of the other installation interfaces, for example after installing to a custom local::lib library tree.
- App::FatPacker is another option.
Vendorisms
Many vendors offer alternate methods of installing Perl modules, usually by converting Perl distributions into a custom ports or package system. These methods are usually not portable beyond the operating system or port or package environment involved, though may suit sites heavily invested in that port or package system:
- 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.
- On Mac OS X, install XCode and consider using one of the various package systems available, for example MacPorts.
- On Windows, ActiveState’s Perl Package Manager (PPM), the FreeBSD ports system, or a package software. However, consider instead StrawBerry Perl.
Note the different naming conventions used by different installation systems. The following commands are equivalent means to install libwww-perl on Debian, via the FreeBSD ports system, yum on RedHat systems:
# apt-get install libwww-perl
# portinstall p5-libwww
# yum -y install perl-libwww-perl
The same Perl distribution has a distinct name in each different package system! When requesting help, note whether the problem is with a Perl module or distribution, or with a vendor port or package of such. A Perl module that cannot be found on CPAN may belong to some vendor application, and help requested from that vendor, not the Perl community.
A site may only use vendor port or package installed perl distributions, or may end up using a mix of vendor supplied data and Perl modules installed to various directories on a system. While individuals can cobble together whatever works for them, larger sites will benefit from increased formalism in how software is installed and maintained.
Automated Testing & Feedback
Use CPAN::Reporter to submit module test results. Try SmokeAuto for automated module testing.
Usage Tips
Consult the usage tips documentation for more information, such as how to perform case sensitive searches, install specific module versions, and more.
How to uninstall Perl modules comes up fairly often. Not sure why, as there are better things to waste time on, and little if nothing to gain from removing modules. (I have similar thoughts on “looking to find what Perl modules are installed on a system” (run perldoc -q installed for some ideas)—never seen a use for such an audit. Perhaps on poorly maintained systems that have who know what installed who knows where?
Debugging 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.
Operating System Particulars
Problems with CPAN on Mac OS X. On Windows, consider Strawberry Perl.
