Module Installation

Chapter 4 - CPAN Module Distributions
by?Sam Tregar?
Apress ? 2002
Companion Web Site

Modules are installed from module distributions using a few simple steps. The CPAN module automates these steps, but let's look at how they work manually. I'll be demonstrating this process on a UNIX system (Redhat Linux to be precise), but with the proper tools listed in Chapter 1 installed, the examples should work on Windows too.

First, you download and uncompress the module. For example, I use lwp-download^[1] to download the Memoize^[2] module from CPAN:

 $ lwp-download http://www.cpan.org/authors/id/M/MJ/MJD/Memoize-1.00.tar.gz Saving to 'Memoize-1.00.tar.gz'... 46.2 KB received in 1 seconds (46.2 KB/sec) 

Then you decompress the module distribution. For example, I decompress Memoize with Gnu tar:

 $ tar zxf Memoize-1.00.tar.gz 

Then I enter the directory created:

 $ cd Memoize-1.00 

To build the Makefile, I run the Perl script Makefile.PL. This script examines my system and builds a Makefile appropriate for my system:

 $ perl Makefile.PL Checking if your kit is complete... Looks good Writing Makefile for Memoize 

Using the Makefile just created, I build the module. The make command follows the instructions in the Makefile. It copies the Perl modules into a staging area called blib that's used to assemble the module before installation. It also builds manual pages from POD source.

 $ make cp Memoize.pm blib/lib/Memoize.pm cp Memoize/ExpireTest.pm blib/lib/Memoize/ExpireTest.pm cp Memoize/Saves.pm blib/lib/Memoize/Saves.pm cp Memoize/Expire.pm blib/lib/Memoize/Expire.pm cp Memoize/AnyDBM_File.pm blib/lib/Memoize/AnyDBM_File.pm cp Memoize/Storable.pm blib/lib/Memoize/Storable.pm cp Memoize/SDBM_File.pm blib/lib/Memoize/SDBM_File.pm cp Memoize/ExpireFile.pm blib/lib/Memoize/ExpireFile.pm cp Memoize/NDBM_File.pm blib/lib/Memoize/NDBM_File.pm Manifying blib/man3/Memoize.3 Manifying blib/man3/Memoize::ExpireTest.3 Manifying blib/man3/Memoize::Saves.3 Manifying blib/man3/Memoize::Expire.3 Manifying blib/man3/Memoize::AnyDBM_File.3 Manifying blib/man3/Memoize::Storable.3 Manifying blib/man3/Memoize::ExpireFile.3 Manifying blib/man3/Memoize::SDBM_File.3 Manifying blib/man3/Memoize::NDBM_File.3 

Next, I test the module with make test:

 $ make test PERL_DL_NONLAZY=1 /usr/local/bin/perl -Iblib/arch -Iblib/lib                      \ -I/usr/local/lib/perl5/5.6.1/i686-linux -I/usr/local/lib/perl5/5.6.1 -e           \ 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t t/array_confusion...ok t/array.............ok t/correctness.......ok t/errors............ok t/expfile...........ok t/expire............ok t/expmod_n..........ok t/expmod_t..........ok t/flush.............ok t/normalize.........ok t/prototype.........ok t/speed.............ok t/tiefeatures.......ok t/tie_gdbm..........ok t/tie_ndbm..........skipped test on this platform t/tie_sdbm..........ok t/tie_storable......ok t/tie...............ok t/unmemoize.........ok All tests successful, 1 test skipped. Files=19, Tests=175, 43 wallclock secs (14.74 cusr + 0.17 csys = 14.91 CPU) 

Finally, I install the module and documentation using make install as root. This takes the contents of blib created previously and moves them into the appropriate places in my system:

 $ su root Password: # make install Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/ExpireTest.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/Saves.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/Expire.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/AnyDBM_File.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/Storable.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/SDBM_File.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/ExpireFile.pm Installing /usr/local/lib/perl5/site_perl/5.6.1/Memoize/NDBM_File.pm Installing /usr/local/man/man3/Memoize.3 Installing /usr/local/man/man3/Memoize::ExpireTest.3 Installing /usr/local/man/man3/Memoize::Saves.3 Installing /usr/local/man/man3/Memoize::Expire.3 Installing /usr/local/man/man3/Memoize::AnyDBM_File.3 Installing /usr/local/man/man3/Memoize::Storable.3 Installing /usr/local/man/man3/Memoize::ExpireFile.3 Installing /usr/local/man/man3/Memoize::SDBM_File.3 Installing /usr/local/man/man3/Memoize::NDBM_File.3 Writing /usr/local/lib/perl5/site_perl/5.6.1/i686-linux/auto/Memoize/.packlist Appending installation info to /usr/local/lib/perl5/5.6.1/i686-linux/perllocal.pod 

The amazing thing about this procedure is that it works for nearly every module on CPAN on nearly every operating system supported by Perl. Virtually every module on CPAN supports the exact same installation procedure. This chapter will explain in detail how each of these steps works and show you how to build a distribution that your users will be able to install as easily as Memoize.

^[1]lwp-download is installed with the LWP module by Gisle Aas.

^[2]Written by Mark-Jason Dominus