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 (App::perlbrew is another option, though does not support the installation of C libraries like MacPorts does). 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 via local::lib. An administrator would need to install Xcode, if that is not available. Perl Software Depots goes into more detail on the management of software installs.
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
If a custom version of Perl is installed, either the PATH environment variable must list that perl first, or the shebang line must be updated to always use the custom perl. I strongly advise against using symlinks to overwrite vendor versions of perl, as this again could cause unexpected problems should Apple release a patch that changes something; also, perl is just one of many commands associated with Perl, so a symlink of just /opt/local/bin/perl to /usr/bin/perl will still cause /usr/bin/cpan to be used, resulting in modules installed for who knows what Perl.
$ which perl
/opt/local/bin/perl
$ type -a perl
perl is /opt/local/bin/perl
perl is /usr/bin/perl
$ head -1 ~/bin/xmltidy
#!/opt/local/bin/perl
Consult the documentation for the shell used on how to configure the PATH environment variable. Note that the PATH and other environment variables may need to be set in the environment.plist file for non-terminal programs such as BBEdit.
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 shipped 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],
