8.2 Using CPAN

Previous Table of Contents Next

8.2 Using CPAN

You can of course download tarballs (compressed archives of file trees created with the tar program) of modules from CPAN and build them manually. I'll show you how to do that shortly. But first, I'll show you the easy way.

8.2.1 Using

Perl makes it phenomenally easy to install most modules by providing a handy layer of automation for talking to CPAN right in the core. That layer is implemented byyou guessed ita module, amazingly enough called[5]

[5] In Perl 5.10 will be superseded by a module called, which you can currently find on CPAN. will provide a cleaner interface for using CPAN. As of this writing it is still somewhat leading edge, so I am not covering it further here, but feel free to experiment with it.

Installing a new module with is extremely easy, especially if you are the system administrator or otherwise have write access to the directories in perl's @INC where it wants to install new modules. To install a module called, say, Mac::iTunes, just type:

% perl -MCPAN -e 'install Mac::iTunes'

What launches into the realm of superstardom is that it can detect and install dependencies; when the module you are installing requires other modules to work (and Mac::iTunes requires a bunch), but you don't already have them. Provided the module author properly listed those prerequisite modules (and the Mac::iTunes author did), then will install those modules; and if any of them have unrequited prerequisites, CPAN will install them, and so forth. If a module in this dependency chain did not specify its prerequisites properly, you can usually get around it by reissuing the original install command after the first attempt fails.

If you want to use to install modules to a private directory (perhaps because you don't have administrator privileges to install to the site_perl targets in the @INC compiled into perl), you have to work a little harder. uses a configuration file that contains settings for, among other things, where to build downloads and where to install completed modules. You need to make a version just for you that has special settings. This file needs to be called and live in a directory .cpan/CPAN under your home directory. You can let build this file for you by typing this command:

% perl -MCPAN -e shell

and answering the questions. However, if the superuser has already done so, you may get a message about permission being denied to access their .cpan directory. In that case, first copy the CPAN::Config module that is part of the installed perl so you can edit it:

% mkdir ~/.cpan

% mkdir ~/.cpan/CPAN

% cp `perl -MCPAN::Config -e 'print $INC{"CPAN/"}'` \


Then edit ~/.cpan/CPAN/ to change the paths of the build_dir, cpan_home, and keep_source_where parameters to point to directories you have write permission for.

Now you can now run in interactive mode:

% perl -MCPAN -e shell

cpan shell -- CPAN exploration and modules installation (v1.76)

ReadLine support available

Now, give a configuration command to the CPAN shell:

cpan> o conf makepl_arg PREFIX=/home/peter/myperl

In this case, /home/peter/myperl is the private directory where you want to install new modules. (Don't try using ~ in this path.) Finally, commit the configuration change (cause the change to makepl_arg to become permanent) and exit the CPAN shell:

cpan> o conf commit

commit: wrote /home/peter/.cpan/CPAN/

cpan> q

Lockfile removed.

You can now build a module using and the install command will put the installed module under /home/peter/myperl. You will need to add the directory /home/peter/myperl/lib/perl5/site_perl to perl's @INC to find the modules that are installed there.[6] Therefore a Perl program that wants to use these modules should start out:

[6] The full story is a bit more gory. Modules can be installed not just under /home/peter/myperl/lib/perl5/site_perl, but under version- and architecture-specific subdirectories therein. So why don't I have to add those directories to @INC as well? Because Perl's use lib pragma and -I command-line option will do it for me: If version- or architecture-specific subdirectories exist for any directory I add to @INC using those operations, they will be added to @INC automatically. That's another good reason to avoid modifying @INC directly.

use lib qw(/home/peter/myperl/lib/perl5/site_perl);

because that directory is not in the default @INC.

8.2.2 Manual Module Installation

On rare occasions won't work for some reason. You may have an idiosyncratic environment, or the module may require some configuration. Modules that require your input to configure are supposed to engage you in an interactive dialog when you issue the install command. The module author programs this dialog in a file called Makefile.PL (see Section 3.3). If the install command doesn't work for a particular module, then you can build it by hand and invoke Makefile.PL yourself. First download the module; the look command in the shell is ideal for that:

% perl -MCPAN -e shell

cpan> look Foo::Bar

[output deleted]

Working directory is /home/peter/.cpan/build/Foo-Bar-0.44


It might look from that last prompt as though the perl command has returned, but in fact it's still running, and has downloaded and unwrapped the latest version of the Foo::Bar module and launched a shell in the build directory for you to play with the module. The manual equivalent of the look command is to download the module's tarball from CPAN (that Download link on, then:

% gunzip Foo-Bar-0.44.tar.gz

% tar xf Foo-Bar-0.44.tar

% rm Foo-Bar-0.44.tar

% cd Foo-Bar-0.44

The first two steps can be combined if your tar program accepts the -z option.

Now look for a README file and peruse it. Normally, the steps to build the module are:

% perl Makefile.PL

% make install

make install will expand in this case to make; make test; make install, with each step being executed only if the previous one succeeds.

Since you're presumably building this module by hand because the install command isn't good enough, rather than some masochistic desire to make life difficult, you'll need to intervene at this stage. Most likely you'll be editing Makefile.PL before the first command. It's hard to imagine legitimate circumstances for editing the Makefile before running make given that you can set just about every parameter in that Makefile that matters through arguments to the first command. To find out more about those arguments, read the documentation for the ExtUtils::MakeMaker module. (That's what Makefile.PL uses to create a Makefile.)

If you began this build process with the look command, remember that you're in a subshell and you need to exit it:

% exit

cpan> q


I sometimes forget this and only find out that I'm still in the shell when I log out at the end of the day.

8.2.3 PPM

On a Windows platform will not be useful due to the absence of the make program. You can either get a version for Windows such as nmake[7] or dmake, get one in a UNIX emulation environment such as Cygwin,[8] or you can take the easier step of using the ppm (Perl Package Manager) program included in ActiveState's Windows Perl distribution.[9] PPM only knows about modules that have been ported to the PPM repository, so it will always lag behind CPAN; but on the other hand, all the compilation has already been done for you, so installation of modules with binary components can be much easier than on a UNIX machine. An extreme example of this is PerlTk, which on UNIX requires that you first acquire and build the underlying Tk and Tcl libraries, whereas on Windows everything will be installed for you with the single PPM install command.



[9] PPM3 in recent versions of Active Perl.

8.2.4 Module Distribution

When you want to package your own module for distribution, the obvious choice today is called ExtUtils::MakeMaker. That's a core module that's invoked by h2xs to create the Makefile.PL when you first create a new module.

If, however, you want to do more than what the default Makefile.PL does, you need to edit it and insert directives drawn from the ExtUtils::MakeMaker documentation. Some people have pointed out lately that this interface is not as easy to use as they would like, and they have started developing alternatives:

  • Ken Williams' Module::Build generates a Build.PL file that can be used to build a distribution without a make utility. As time goes by, more CPAN modules will incorporate Module::Build and and will be upgraded to recognize Build.PL files (

  • However, Module::Build addresses how a user installs a module, not how a developer creates one. Geoffrey Avery created an alternative to h2xs in Extutils::ModuleMaker ( It even knows how to generate Build.PL files.

  • Autrijus Tang's PAR (Perl ARchive) can create self-contained executables that encapsulate all their dependencies. It employs highly sophisticated code to find those dependencies and works on a wide variety of platforms (

Expect that in the next few years these modules will get greater attention and more widespread use.

    Previous Table of Contents Next
    © 2000- NIV