Perl Programming/CPAN

CPAN

A huge collection of freely usable Perl modules, ranging from advanced mathematics to database connectivity, networking and more, can be downloaded from a network of sites called CPAN. Most or all of the software on CPAN is also available under either the Artistic License, the GPL, or both. CPAN.pm is also the name of the Perl module that downloads and installs other Perl modules from one of the CPAN mirror sites; such installations can be done with interactive prompts, or can be fully automated.

Look for modules on CPAN

Installing modules

With ActivePerl (Windows systems)

From a command-line, type the command

ppm

This will give you a "Perl Package Manager" prompt, which allows you to download and install modules from the internet. For example, to install the Time::HiRes module, type:

search time::hires

That will give you a list of modules that match your search query. Once you know the module is available and what its exact name is, you can install the module with:

install Time::HiRes

With Perl

If you're using a normal version of Perl, the way to activate the package manager is this:

perl -MCPAN -e shell;

This will load the CPAN module, and let you search for, download, install, and manage the modules on your computer the same as PPM.

With Perl (cpanm)

The Perl module cpanm (CPAN Minus) is another alternative for installing modules from the CPAN library cpanminus.pm.

cpanm can be installed and used like this on a UNIX-like system:

curl -L "http://cpanmin.us" >cpanm
chmod +x cpanm
./cpanm LWP::Bundle

One must have root privileges in order to install module in the system-wide directories, however alternatives exist such as local::lib, which allows regular users to install and use Perl modules in their home folder lib.pm.

With Strawberry Perl (Windows systems)

Strawberry Perl also includes the CPAN module, so you can use the command above to activate the package manager.

The start menu, however, also includes a shortcut (with the name of "CPAN Client") so that you don't have to go to a command line to do so.

A number of modules are already included in Strawberry Perl, beyond what comes with a normal version of Perl, or what comes with ActivePerl, so you may wish to check, if the module you want is already installed before you start the CPAN client.

Using a module in your program

To incorporate a module into your program, use the use keyword:

use Time::HiRes;

You can supply an optional list of the functions you want to use from this module, if you're worried that some of the function names in the module are too similar to functions you're already using:

use Time::Hires qw(time gmtime);

With that done, you can simply use the supplied functions as normal. Most modules have example programs within their documentation, and the best way to start using a module is to copy and adapt one of the example programs.

Finding documentation

The documentation for each module is installed in your documentation directory when you get a new module, or you can browse documentation on search.cpan.org and perldoc.perl.org.

Unix systems

On Unix systems, the documentation is usually installed as man pages in section 3p so that the command below will work:

man 3p Module::Name

perldoc Module::Name will also work.

If you want documentation that is browseable in a web browser, you can install Perldoc::Server as noted below.

Windows systems running ActivePerl

Module documentation is installed as HTML files in ActivePerl. To find those files, try looking in some of the following directories:

• C:\Perl\html\lib
• C:\Perl\html\site\lib

If you're having real trouble finding the HTML documentation for a module, you may be able to read the *.pm Perl file yourself for POD comments, or use the pod2html tool yourself to generate the HTML file.

Windows systems running Strawberry Perl

Strawberry Perl does not install module documentation as either manpages or html files. Instead, you can run the perldoc command to display module documentation.

perldoc Module::Name

You can also use Perldoc::Server to display module documentation, as illustrated below.

Perldoc::Server

The Perldoc::Server module (that can be installed via CPAN) will provide a local server that will display HTML files "on the fly" from Perl's documentation and the documentation for installed modules. Install it, and the command

perldoc-server

will be in your path. Run it, and then browse to http://localhost:7375/ in your Web browser to see the documentation.

Note that the perldoc-server command must be running to provide the documentation using this method.

Contributing your own modules to CPAN

In the event that a module you need isn't available on CPAN, the usual answer is to write the module yourself and add it to CPAN. That way, nobody else needs to waste time creating the same functionality that you're already written.

See How to contribute modules to CPAN