Thursday, March 15, 2007

Installing Perl Modules

This tutorial has been my guide now for quite a while... i hope you like it as much as i am.


CPAN

The Comprehensive Perl Archive Network (CPAN) holds many Perl modules and scripts, distributed among a large number of mirrors. The CPAN module provides an interface to query and install modules from CPAN. These notes document the setup and usage of CPAN, with attention to common tasks and pitfalls along the way.

Any Perl modules used by a site should be archived locally. Doing so ensures the modules can be installed on new systems, even if removed from CPAN.

Use CPAN::Reporter to submit module test results. Try SmokeAuto to automate 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. 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.

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 bug, install the latest version of CPAN first. Setting the FTP_PASSIVE=1 environment variable avoids another common problem where active File Transfer Protocol (FTP) connections are blocked by a local firewall.

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

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. Persue 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.

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 following 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 (stored somewhere under the perl @INC path list) to edit with the following command.

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

Usage Tips

Invocation | autobundle | Debugging | Old Modules | Mac OS X | Manual Build | sudo | Uninstalling | Upgrading

Once the latest version of CPAN has been properly installed, it is safe to install Bundle::CPAN to get the latest versions of modules CPAN depends on. If already in the CPAN shell, be sure to run reload cpan first.

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

The following sections outline various uses and caveats with CPAN.

Invocation

The latest version of CPAN should install a cpan command somewhere on the system, which is easier to use than the traditional means of calling CPAN. 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 in question, 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. Consult your shell’s documentation for more information on whether this is required.

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.

Debugging

Should tests fail during the make test phase of the module install process, the tests should be investigated to determine their impact. If the failed tests are not relevant to the system in question, the module can be installed with the force option. Otherwise, filing a bug report or otherwise contacting the module author may be in order.

  • Force Install

To force install a module, use the force option.

cpan> force install HTML::Mason

  • Verbose Testing

More verbose testing will need to be done from the command line. This can be done with the look command from the CPAN shell, along with subsequent shell code as shown in the following example for HTML::Mason, with verbose test logging saved to test.log via the tee(1) command.

cpan> install HTML::Mason
Running install for module HTML::Mason
Running make for D/DR/DROLSKY/HTML-Mason-1.23.tar.gz
…
t/02a-filter..........ok
t/04-misc.............FAILED tests 9-10
Failed 2/11 tests, 81.82% okay
t/05-request..........ok
…
Failed Test Stat Wstat Total Fail Failed List of Failed
---------------------------------------------------------------------------
t/04-misc.t 11 2 18.18% 9-10
2 tests skipped.
Failed 1/23 test scripts, 95.65% okay. 2/376 subtests failed, 99.47% okay.
*** Error code 35

Stop in /var/spool/cpan/build/HTML-Mason-1.23.
/usr/bin/make test -- NOT OK
Running make install
make test had returned bad status, won't install without force

cpan>
cpan> look HTML::Mason
Running look for module HTML::Mason

Trying to open a subshell in the build directory...
Working directory is /var/spool/cpan/build/HTML-Mason-1.23
# make test TEST_VERBOSE=1 TEST_FILE=t/04-misc.t | tee test.log
…

Determination as to whether the failed test is relevant to the system in question will need to be done by a human, typically by running of the test code and consulting the test script and module code to see what is failing. If the failed tests are for features of the module that will not be used, then the module typically can be installed and used without problems.

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.

Mac OS X

Problems with CPAN on Mac OS X.

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

Uninstalling

CPAN itself offers no uninstall method. Several of the alternatives to CPAN do, such as CPANPLUS or vendor package/port systems. If the module has been fully installed along with a .packlist file for the module, the ExtUtils::Packlist perl module documentation includes code for a modrm command to cleanly remove an installed module.

Modules built with other tools, such as Module::Build, may not write out a .packlist file for use by ExtUtils::Packlist.

Upgrading

How to upgrade all the modules on the system like apt-get is actually documented in the CPAN manual; however, the question comes up often enough that I answer it here as well.

# install everything that is outdated on my disk:
# perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'

Problems with this include new versions of modules that may break old module behavior, or various modules that cannot be upgraded due to build failures or system incompatibilities. Best to subject a test system to this sort of mass module upgrade before attempting it on a production system.



if you need to change server pls check this cool site below

CPAN SERVER SITES:

http://www.cpan.org/SITES.html

Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)