5.7 Pre-Defined and Downloadable Modules
Perl has a large number of pre-defined modules. The modules are all downloadable from The Comprehensive Perl Archive Network (CPAN) at www.cpan.org or many of its mirror or copy sites. For Unix machines including Macintosh OS X, modules are easily downloadable and installable. For a Windows system, a large number of modules are available from www.activestate.com in addition to CPAN. The modules available at www.activestate.com are a subset of those found at CPAN. These are the best choice for downloading if the Perl running is ActivePerl. ActivePerl is easy to install on Windows systems. On a Unix machine, one should use
%perl -MCPAN -e shell
to manage modules including installation. ActivePerl contains a program called ppm (Perl Package Manager) to perform similar tasks. Perl is usually able to download and install modules from CPAN or one of its many mirrors on its own. But, sometimes it fails. In such a case, one should try the following steps. The steps are clearly spelled out at the CPAN Web site for many different kinds of machines. The details given below pertain to Unix or Unix-like systems only.
1. Find the module’s source file and download it to one’s system. One must have root or super-user permission to install modules in general. On Unix machines permissions are an issue, but not usually on Windows or Macintosh machines prior to OS X. It is possible to install Perl modules in one’s own directory as a user. But, in such a case, they are unavailable to any other user unless the permissions are changed. The downloaded file comes with a .tar.gz extension. In particular, the example module we install for illustration purposes is FreezeThaw, version 0.41.
Its compressed source archive file found at CPAN is FreezeThaw-0.41.tar.gz. This module is able to store complex data in a file in string form and later retrieve it from the file in its original form.
2. This file has been compressed using the GNU compression program gzip. Therefore, it has to be uncompressed.
%gunzip FreezeThaw-0.41.tar.gz
This produces a file FreezeThaw-0.41.tar. This a so-called tar archive and should be unarchived.
%tar -xvf FreezeThaw-0.41.tar
FreezeThaw-0.41/
FreezeThaw-0.41/Changes
FreezeThaw-0.41/FreezeThaw.pm
FreezeThaw-0.41/Makefile.PL
FreezeThaw-0.41/MANIFEST
FreezeThaw-0.41/README
FreezeThaw-0.41/t/
FreezeThaw-0.41/t/FreezeThaw.t
In the particular case under consideration, this produces a directory called FreezeThaw-0.41 in the current directory. It usually has the following files among many others: MANIFEST, Makefile.PL, README., and test.pl. It may have sub-directories. Many Perl modules are not pure Perl modules, but have many files in C. Therefore, many C language files may be present. In addition, files with extensions .xs, .xsi, .xst, etc., may appear. These files allow a C language program to be linked to Perl programs. We do not discuss how this can be done here.
3. We go to the FreezeThaw-0.41 directory by cding to it. The MANIFEST file usually lists the important files. This is what the file contains for the FreezeThaw module.
FreezeThaw.pm
t/FreezeThaw.t
MANIFEST
Makefile.PL
Changes
README
We can read the README file to see how the installation process should proceed next. The
Makefile.PL file looks like the following.
use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
WriteMakefile(
NAME => 'FreezeThaw',
VERSION_FROM => "FreezeThaw.pm",
);
The Makefile.PL is a Perl program that uses a package called ExtUtils::MakeMaker. Without worrying about the details of what actually happens, in short, it probes the current computer system for the existence of various software tools and libraries that are essential for performing the installation process. Executing the Makefile.PL script creates a file called Makefile.
%perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for FreezeThaw
Usually, the output is a lot longer. It produces a file called Makefile suited to the current system. The Makefile file is usually quite long and contains instructions regarding how the source should be compiled, how tests should be performed, and how temporary directories and files created should be cleaned up after installation, etc.
4. We next run the following command.
%make
In this case, the printout is like the following.
mkdir blib
mkdir blib/lib
mkdir blib/arch
mkdir blib/arch/auto
mkdir blib/arch/auto/FreezeThaw
mkdir blib/lib/auto
mkdir blib/lib/auto/FreezeThaw
mkdir blib/man3
cp FreezeThaw.pm blib/lib/FreezeThaw.pm
Manifying blib/man3/FreezeThaw.3pm
It looks at the Makefile file and compiles with the right flags, i.e., with the appropriate compiler options. It usually uses a C compiler. The next command to run is the following.
%make test
PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib
-I/usr/lib/perl5/5.6.0/i386-linux -I/usr/lib/perl5/5.6.0
-e 'use Test::Harness qw(&runtests $verbose); $verbose=0;
runtests @ARGV;' t/*.t
t/FreezeThaw........ok
All tests successful.
Files=1, Tests=27, 0 wallclock secs ( 0.19 cusr + 0.01 csys = 0.20 CPU)
This runs one or more specified tests that come with the distribution. Some tests may fail. But, the installation can proceed even if some of the tests fail. Quite frequently, automatic installation of Perl modules using
%perl -MCPAN -e shell
fails because some tests do not succeed. But, using the manual process we are undertaking now, the installation can still be made, even though the module is not 100% functional.
5. Finally, if most tests are satisfied, we can go ahead and install by typing the following.
%make install
Installing /usr/lib/perl5/site_perl/5.6.0/FreezeThaw.pm
Installing /usr/share/man/man3/FreezeThaw.3pm
Writing /usr/lib/perl5/site_perl/5.6.0/i386-linux/auto/FreezeThaw/.packlist
Appending installation info to /usr/lib/perl5/5.6.0/i386-linux/perllocal.pod
This process, if successful, places the module’s files in the appropriate places. It also places the documentation in the right place. Documentation for an installed module can be read by running the perldoc system command with the module name as the argument. On a Red Hat Linux machine, the usual location is in sub-directories below /usr/lib/perl5/. The files may be distributed into several directories.
The process discussed works only on Unix systems including Mac OS X. Similar steps exist for Windows systems when downloading a module from CPAN. If ActivePerl is the version of Perl, an easy-to-run program called ppm helps install modules very easily. Not all modules are available at the ActivePerl site. So, even on a Windows machine, once in a while we have to through an elaborate process.