Perl/Modules on CPAN

As you learn to use Perl you'll use more than just the language syntax. In order to use it effectively, you'll need to learn to use modules from the Comprehensive Perl Archive Network (CPAN). This is an invaluable resource for the Perl community - and like many other Open Source projects, it's entirely operated by volunteers and generous sponsors. Many people around the world contribute to CPAN in the following ways:

• They write Perl modules for CPAN, or submit patches and bug reports to authors.
• They provide servers which provide local mirrors of the modules in their part of the world.
• They test modules which others have uploaded and report their results.
• And there are more ways to contribute.

Online Resources Remember and save these references. You will use them when developing any significant amounts of Perl code. The CPAN web site is at http://www.cpan.org/ which includes lists of popular CPAN modules. But remember there isn't a single page with all the CPAN modules - there are just too many for that. A CPAN search engine is at http://search.span.org/

Installing Perl modules from CPAN

Your perl installation should come with the perlmodinstall manual page which documents how to install Perl modules from CPAN. We'll include a summary here. But you should also refer there for specifics for your system, whether you're on a Unix, Windows, Mac or other system.

Perl comes with the CPAN.pm module which handles most details of downloading, building and installing Perl modules from CPAN. It even loads other modules that are dependencies of the modules you request, if needed. One thing you'll quickly notice is that all Perl modules, whether from CPAN or direct from their authors, end in a .pm file suffix. It stands for "perl module". When installed on your system in a directory where Perl can find it, it can be used by any Perl script simply by its name.

Making your own CPAN workspace

In order to learn how to use CPAN without needing system administrator privileges or interfering with system-wide modules already installed on your system, you'll want to make a private workspace. On systems with a command line shell (Unix, Mac and Windows/Cygwin), you can use this shell script. (Windows users on Cygwin can run the script but will need to use backslashes (\) instead of slashes (/) in directory paths. )

Call the script "cpan-wv" so that we're all using the same name for it in the following discussion.

#!/bin/sh
# Wikiversity CPAN shell with user-private workspace

# set private directory path
# you need to set this to a directory which exists and you own
dir=/home/username/lib/perl

# set environment and launch CPAN shell
export PREFIX=$dir
export PERL5LIB=$PREFIX/lib
export PERL_MM_OPT="LIB=$PREFIX/lib INST_LIB=$PREFIX/lib PREFIX=$PREFIX SITEPREFIX=$PREFIX VENDORPREFIX=$PREFIX"
/usr/bin/perl -I$dir/lib -MCPAN -e shell

In order to make the script executable, don't forget to run "chmod a+rx cpan-wv" on it. Then run the script just as "cpan-wv".

The first time you run it, you will see that CPAN is initializing some data files. We have a little work to do helping CPAN settle down on your system. This is just a one-time setup - then you can benefit from it every time you run cpan-wv in the future. Here are prompts you'll see and answers you should give it. In each case, if there is a default answer, it will be in square brackets - that's what you'll get if you just hit Enter. The defaults that are presented to you will probably differ in some cases on your system as Perl determines a different answer is more appropriate. In most cases, the default will be correct or good enough.

Are you ready for manual configuration? [yes]

Hit Enter.

CPAN build and cache directory? [/home/username/.cpan]

Cache size for build directory (in MB)? [10]

Perform cache scanning (atstart or never)? [atstart]

Cache metadata (yes/no)? [yes]

Your terminal expects ISO-8859-1 (yes/no)? [yes]

File to save your history? [/home/username/.cpan/histfile]
Number of lines to save? [100]

Hit Enter at each of these prompts.

Policy on building prerequisites (follow, ask or ignore)? [ask]

For this one, we're going to have CPAN do more work for us. Tell it "follow" and hit Enter.

That means that when CPAN identified other modules which are dependencies of ones that you request, it will automatically install them too. In some cases modules have so many dependencies that it would be tedious to have to approve each and every one. It's acceptable to do this automatically for your personal workspace. You might or might not choose to do that for a production server depending on your circumstances.

Where is your gzip program? [/bin/gzip] 
Where is your tar program? [/bin/tar] 
Where is your unzip program? [/usr/bin/unzip] 
Where is your make program? [/usr/bin/make] 
Where is your links program? [/usr/bin/links] 
Where is your wget program? [/usr/bin/wget] 
Where is your ncftpget program? [/usr/bin/ncftpget] 
Warning: ftp not found in PATH
Where is your ftp program? [] 
Where is your gpg program? [/usr/bin/gpg] 
What is your favorite pager program? [/usr/bin/less] 
What is your favorite shell? [/bin/bash]

Hit Enter at each of these prompts. Optionally, if any are blank, Perl didn't find the program. If you have it and know where it is, you can enter its full path.

If you don't understand this question, just press ENTER.

Parameters for the 'perl Makefile.PL' command?
Typical frequently used settings:

    PREFIX=~/perl       non-root users (please see manual for more hints)

Your choice:  []

Parameters for the 'make' command?
Typical frequently used setting:

    -j3              dual processor system

Your choice:  []

Parameters for the 'make install' command?
Typical frequently used setting:

    UNINST=1         to always uninstall potentially conflicting files

Your choice:  []

Sometimes you may wish to leave the processes run by CPAN alone
without caring about them. As sometimes the Makefile.PL contains
question you're expected to answer, you can set a timer that will
kill a 'perl Makefile.PL' process after the specified time in seconds.

If you set this value to 0, these processes will wait forever. This is
the default and recommended setting.

Timeout for inactivity during Makefile.PL? [0]

Hit Enter for all of these. One of these parameters was already provided by the cpan-wv script. Some of the defaults are coming from Perl, which saved information about how it was built on your system.

Then you'll be prompted for your network configuration.

Your ftp_proxy?
Your http_proxy?
Your no_proxy?

If you need to tell CPAN to access the Internet through a proxy, this is the place to do it. If you don't know, then hit Enter. If that doesn't work, ask your system administrator or service provider what network settings you should use.

On the next step, you're on your own for a moment. You need to select one or more CPAN mirrors that you will use. Select your continent and country to find servers which are in your part of the world. If there aren't any servers in your country, try the nearest country listed that you expect will be closely connected to yours by telecommunications lines.

Tip: you can use the ping and traceroute commands to test which servers are responsive and nearest to your location.

When you find three good ones, call it done and move on. If you can't find three nearby, use the nearest two you can find and add http://www.perl.com/CPAN/ as the last one.

With that CPAN will save the configuration. It will use it again when you run "cpan-wv".

Exercise: install your first CPAN module The cpan-wv script above leaves you in the CPAN shell. When you want to exit, just use your operating system's end-of-file key (usually CTRL-D on Unix and CTRL-Z on Windows). At the CPAN shell prompt, type the following command, which will install a Perl module from CPAN called Wikiversity::Hello. install Wikiversity::Hello If there are any build, install or test errors, the module will not be installed. You'll need to read the errors to determine if there's anything you need to change or fix on your system. Once the module is installed, you should be able to bring up documentation. Exit from cpan-wv back to the system shell. Since it's in your workspace, we need to give Perl its location. Just add "lib" to the path you used in cpan-wv for your workspace path - that's a directory which CPAN created in your workspace. So use that path in the "-I" parameter in the following command. perldoc -I/home/username/cpan/lib Wikiversity::Hello You can run the code with this command, making the same addition to Perl's module path so that it can find it in your workspace. perl -I/home/username/cpan/lib -MWikiversity::Hello -e hurrah When everything works, you will receive words of congratulations. That's all this module does.