CPAN on Mac OS X

The Comprehensive Perl Archive Network (CPAN) is a collection of Perl modules and scripts distributed among a large number of mirror sites. CPAN is also the name of a perl module which provides an interface to install modules from CPAN. These notes document problems with CPAN on Mac OS X. See also the main Life with CPAN documentation.

Xcode (via Developer Tools must be installed (installing Xcode also installs the Perl documentation on Mac OS X). Another option is to run another Unix, such as Debian, under a virtual machine, and install whatever modules are required for development into the sandbox system.

Upgrade System Perl?

I advise against upgrading the system perl, and against installing Perl modules into the system @INC directories. If a different version of perl is required, install it from MacPorts or some other package or ports system. Changing the system perl may break any scripts that rely on a particular version of software installed; Apple updates could also break the perl or new modules improperly installed into the system area. Keep the vendor space separate from any local or site changes where possible. Administrative access is not necessary to install modules, as these can be installed into local directories. An administrator would need to install Xcode, if that is not available.

As of Mac OS X 10.6, the OS ships with multiple versions of perl installed. Peruse the perl(1) manual page on Mac OS X for more details on how to switch between the two, if necessary.

$ sw_vers
ProductName: Mac OS X
ProductVersion: 10.6.3
BuildVersion: 10D573
$ perl -e 'system "ls $_/perl5*" for split /:/, $ENV{PATH}' 2>/dev/null
/usr/bin/perl5.10.0 /usr/bin/perl5.8.9

Case Folding Filesystem

The default filesystem on Mac OS X (HFS+) folds case, unlike traditional Unix filesystems. Unix software that assumes HEAD and head are two different things on Mac OS X will end badly. For example, the LWP::UserAgent module installs /usr/bin/HEAD, which clobbers the existing /usr/bin/head utility. Solutions to this include not installing the HEAD and similar shortcuts, or ensuring these utilities are installed under /usr/local/bin instead. One way is to update the perl Makefile.PL arguments to install third-party utilities into a different directory than /usr/bin.

cpan> o conf makepl_arg "INSTALLBIN=/usr/local/bin INSTALLSCRIPT=/usr/local/bin"
cpan> o conf commit

Due to the rise in popularity of Mac OS X, most of these issues have been worked around in popular modules, such as LWP::UserAgent. However, older, or less frequently used modules may still contain code that assumes filesystem case sensitivity.

Panther (10.3) and /man

Perl 5.8.1 on Mac OS X 10.3 ships with broken settings that cause some modules installed from CPAN to install their manuals under the /man directory. This directory pollutes the root namespace, and is outside the places manuals are searched for by man(1).

To fix this problem, update the makepl_arg to set INSTALLSITEMAN1DIR and INSTALLSITEMAN3DIR manually.

$ grep makepl_arg /System/Library/Perl/5.8.1/CPAN/Config.pm
'makepl_arg' => q[INSTALLSITEMAN1DIR=/usr/share/man/man1 ↵
INSTALLSITEMAN3DIR=/usr/share/man/man3],