\chapter{Administration\label{chap:cpan}}

In this appendix, you would learn how to: \\
\begin{itemize}
\item Install a Perl Module from the CPAN
\end{itemize}

\section{CPAN}

Perl has a very active user community. This is evinced by the gigantic list of modules 
available on the Comprehensive Perl Archive Network (CPAN). CPAN is the central warehouse 
where you can search for existing Perl modules other Perl programmers have contributed to
the community. You will be surprised that the CPAN contains modules of virtually any
category you can think of. By using existing modules on the CPAN you can enforce code reuse
and cut down both development time and cost by not \textit{reinventing the wheel}. Even if
you are not writing programs in Perl, for example, when you are a system administrator at
a web hosting company offering Perl-enabled hosting packages, you still need to know how
to install Perl modules your users may need. \\ 

\subsection{Accessing the Module Database on the Web}

You can browse the module list at \link{http://www.cpan.org/modules/01modules.index.html}{http://www.cpan.org/modules/01modules.index.html}. 
However, in my opinion the best way to locate modules is to use the module search engine. 
There are several engines available on CPAN, and I generally use \link{http://search.cpan.org}{http://search.cpan.org}
because the interface is more neatly, if you know part of the module name already. If you don't
know the name of a module and would like to search through the module description, then 
\link{http://kobesearch.cpan.org}{http://kobesearch.cpan.org} would be more useful to you,
and it is actually more powerful. You may download the source packages and read the 
documentation online. If you intend to install the modules in the traditional way (but 
manually), you may also download the source packages there. \\

\subsection{Package Managers}

\subsubsection{Perl Package Manager}

As most Windows systems are not equipped with a suitable compiler suite (for example, Microsoft 
Visual C++), and some Perl modules contain portions written in C for performance improvements 
(see below), Perl modules are usually distributed in the form of packages. In case a module
has to be compiled before use, it is compiled before being put into the package. The packages are constructed
by volunteers who have the compiler to compile the modules, and the packages generated are then
contributed to the community. Therefore, from a user's point of view this is very convenient 
as all he or she needs to do to install a module is to fetch the package and install it, and 
it's then ready for use. \\

Activestate Perl (most likely on the Windows platform) distribution comes with a package
manager PPM that I found to be quite convenient to work with. Through this package manager, packages
can be automatically fetched from a remote server and installed. It also includes tools to
keep your modules up to date. \\

To start PPM, select ``Perl Package Manager'' from the ``ActiveState ActivePerl 5.8'' program 
group on the Start menu. You would see a prompt \mono{ppm>} which gives you a command-line
interface to type your maintenance commands. Don't be frightened by a command-line interface
in case it looks awkward to you (this is a GUI age, after all). It is very easy to use and
you can always access help information by typing \mono{help} alone. To get help information
on module upgrades, type \mono{help upgrade} etc. \\

To start with, you would first try to search for modules in the module repository. Try to
type in \mono{search Crypt} to see a list of cryptographic modules available. By default, PPM would
searches for modules by name only. You can use logical operators \mono{and}, \mono{or} and 
\mono{not} in the query string. To match both the module name and description, use the 
command \mono{search Crypt or ABSTRACT='Crypt'}. To install a package, note the package name
and use the command \mono{install}, for example \mono{install Crypt-TripleDES}. The latest 
stable version of the \mono{Crypt::TripleDES} module is automatically downloaded and installed.
To keep your modules constantly up to date, type \mono{upgrade * -install} to upgrade any
packages that are out of date to the latest version. You can browse a list of packages installed
by \mono{query *}. \\

This section is meant to give you an overview of the most commonly performed operations
with PPM. Please read the documentation bundled with ActiveState ActivePerl for further
information. However, because not all modules are already packaged for PPM, you may not
be able to use this method for some modules. \\

\subsection{Installing Modules using CPAN.pm}

If your Perl distribution does not come with a package manager like PPM, as is the case
for most Unix variants, there is still an easy way to compile and install modules on 
the CPAN without resorting to the traditional, but manual method (to be described next).
It is to use the CPAN.pm module that is bundled with your Perl distribution (should be,
but please check it for sure). This module gives you a convenient way to automate the
regular extract-configure-compile-install steps. It does not give you as many features
as PPM, but it is more than adequate if you would just like to install a module in an 
easy way. However, a new module called CPANPLUS.pm is going to replace CPAN.pm in future
Perl releases, offering a few more features. You may wish to use it instead of CPAN.pm.
However, as of this writing it is not bundled in perl so you have to install it separately.
The instructions below apply to CPANPLUS as well, but please replace CPAN with CPANPLUS. \\

You can use CPAN.pm in two ways. If you have tried PPM above, you can also have a shell-like
command line interface where you can type the maintenance commands. Alternatively, to 
quickly install a module you may not wish to go into the CPAN.pm shell and you can simply
type it on your system command line. Both methods are covered below. To start the CPAN.pm
shell, type \mono{perl -MCPAN -e shell} on the command prompt. Note that very likely you 
need to be the system administrator (root) in order to start the CPAN shell. \\

\begin{lstlisting}[numbers=none,backgroundcolor=\color{CodeBackground}]
cbkihong:~# perl -MCPAN -e shell

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

cpan> h

Display Information
 command  argument          description
 a,b,d,m  WORD or /REGEXP/  about authors, bundles, distributions, modules
 i        WORD or /REGEXP/  about anything of above
 r        NONE              reinstall recommendations
 ls       AUTHOR            about files in the author's directory

Download, Test, Make, Install...
 get                        download
 make                       make (implies get)
 test      MODULES,         make test (implies make)
 install   DISTS, BUNDLES   make install (implies test)
 clean                      make clean
 look                       open subshell in these dists' directories
 readme                     display these dists' README files

Other
 h,?           display this menu       ! perl-code   eval a perl command
 o conf [opt]  set and query options   q             quit the cpan shell
 reload cpan   load CPAN.pm again      reload index  load newer indices
 autobundle    Snapshot                force cmd     unconditionally do cmd
\end{lstlisting}
\addvspace{\baselineskip}

To install a module, for example, \mono{Crypt::DES}, you can use the command \mono{install Crypt::DES}.
The module would be downloaded from a local package repository, extracted, compiled, tested and finally
installed on your system. Meanwhile you would see a lot of messages printed on the screen. Errors, if any,
will also be printed. Therefore, if the process suddenly stops in the middle and there are some errors 
printed, you should try your best to locate the source of the error. Usually, it may be that you have 
certain prerequisites not met yet. You should look at the documentation that comes with a module
if problems arise to see if they are addressed in there. If you don't want to use the CPAN shell, you can
specify the command on the command line, for example, \mono{perl -MCPAN -e install Crypt::DES}. \\

Apart from modules, you can install \term{bundles} through the CPAN module. A bundle is a set of related
modules that are packaged together. Usually a module requires a set of other modules, and in this case, the
packager may prefer to package all of them as a bundle. An example of a bundle is \mono{Bundle::DBD::mysql},
which includes the modules \mono{DBI}, \mono{DBD::mysql}, \mono{Data::ShowTable} and \mono{MySQL}. Each bundle
has a bundle file which lists the modules covered. The \mono{autobundle} command of your CPAN shell lets you
create a bundle file which lists the modules that are currently installed on your system. For example, if
you are a system administrator for a Web host you can maintain a current list of modules on a single system
and have the other systems share the bundle file to ensure that all servers are installed the same versions
of Perl modules. For more information, please see the CPAN manpage. \\

\subsection{Installing Modules --- The Traditional Way}

The traditional way is to download the compressed source package from the CPAN as mentioned 
above, and extract it. This method should in general only be used if the CPAN.pm module isn't 
or cannot be set up properly. The packages are compressed with gzip, a popular compressing tool on 
the Unix platform. You can extract the package by the command \mono{tar xvzf \textsl{package.tar.gz}}
. If your version of tar(1) does not support the `z' switch, you will need to try 
\mono{zcat \textsl{package.tar.gz} | tar xvf -}. On Windows you can decompress gzipped 
tarballs with software like Winzip or PowerArchiver. After the package is extracted, change
to the directory containing the extracted sources on the command line using the \texttt{cd}
command. Now the Makefile needs to be created. Run the Makefile generation program by 
\mono{perl Makefile.PL}. The program detects the settings of your Perl installation and 
creates the site-dependent Makefile (that explains why the Makefile is not included in the
sources). To execute the Makefile, you need a make tool which coordinates the whole compilation
session. On most Unix systems you should have a version of make already available. If you are on 
Windows, you need to have Visual C++ installed for compilation. nmake is included in the 
Visual C++ installation. Because nmake may not be on your PATH, you may need to use the
Visual Studio command prompt which adds the necessary paths to the PATH so that the necessary
tools can be invoked without specifying path. On Unix, type \mono{make}; while on Windows 
\mono{nmake}. The files would then be compiled. Then type \mono{make install} or \mono{nmake install}
to copy the necessary files to the correct location. Note that modules installed in this 
way are not recognized by any package managers. \\

Although Perl source files are generally portable, some modules have to make use of the 
XS mechanism to delegate part of the program in C for performance considerations, or when
they need to interface with the system native libraries in order to function. That's why
compilation is sometimes needed. If compilation is needed you need to have a working installation
of the C compiler available. For ActiveState Perl the compiler required is \mono{cl.exe} of 
Visual C++, and gcc on Unix platforms. If you don't have a compiler, you can still install
modules which do not use the XS mechanism (that is, there are no .xs files in the bundle).
On Windows, nmake is free and you can download from 
\link{ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe}{ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe}
which is a self-extracted executable. \\

\section*{Web Links}

\begin{list}{\thechapter.\arabic{count}}{\usecounter{count}}
\item {
	\link{http://www.perldoc.com/perl5.8.0/pod/perlmodinstall.html}{perlmodinstall manpage --- Installing CPAN modules} \\
	\textit{http://www.perldoc.com/perl5.8.0/pod/perlmodinstall.html}
}
\end{list}
