Installing CPAN Modules

Chapter 1 - CPAN
by?Sam Tregar?
Apress ? 2002
has companion web siteCompanion Web Site

So, you've found the module you've been searching for. Now you'll need to install it. And, like many things in Perl, TMTOWTDI.[6] The sections that follow discuss the two main installation methods: the easy way and the hard way.

The Easy Way

I'll start with the easy way—if you encounter problems, you should consult the "The Hard Way" section later in this chapter.

Recent versions of Perl come with a module called CPAN,[7] which as you might have guessed is used to access the contents of CPAN. The CPAN module makes installing CPAN modules incredibly easy. It downloads modules from CPAN and automatically follows their dependencies, saving you a lot of work (which you'll learn all about in the upcoming section, "The Hard Way").

To get started with the CPAN module, enter the following command:

 # perl -MCPAN -e shell 

If you're using a UNIX system and want to install modules system-wide, you'll have to run this command as the root user. It is possible to use the CPAN module as a normal user, but you won't be able to install modules into the system.

The first time you run this command the CPAN module will ask you a series of questions:

 # perl -MCPAN -e shell CPAN is the world-wide archive of perl resources. It consists of about 100 sites that all replicate the same contents all around the globe. Many countries have at least one CPAN site already. The resources found on CPAN are easily accessible with the CPAN.pm module. If you want to use CPAN.pm, you have to configure it properly. If you do not want to enter a dialog now, you can answer 'no' to this question and I'll try to autoconfigure. (Note: you can revisit this dialog anytime later by typing 'o conf init' at the cpan prompt.) Are you ready for manual configuration? [yes] 

Each question has a default answer in square brackets. In most cases the default will be correct and you can just press Enter to continue. One important question to look for is this one, about following prerequisites:

 The CPAN module can detect when a module that which you are trying to build depends on prerequisites. If this happens, it can build the prerequisites for you automatically ('follow'), ask you for confirmation ('ask'), or just ignore them ('ignore'). Please set your policy to one of the three values. Policy on building prerequisites (follow, ask or ignore)? [ask] 

The default, ask, is the most conservative setting, but you should consider answering follow since this will greatly ease the task of installing modules with lots of dependencies.

The CPAN modules uses various external programs, and you'll be asked to confirm their location:

 Where is your gzip program? [/bin/gzip] 

If you don't want the CPAN module to use a particular external program type a space and press Enter. This can be useful if you know a program is broken on your system or won't be able to perform its task.

Towards the end of the questions, the CPAN module will present you with a choice of which mirrors to use. First, you'll identify your continent:

 (1) Africa (2) Asia (3) Central America (4) Europe (5) North America (6) Oceania (7) South America Select your continent (or several nearby continents) [] 

then country:

 (1) Canada (2) Mexico (3) United States Select your country (or several nearby countries) [] 

and finally you'll select several mirrors from a list:

 (1) ftp://archive.progeny.com/CPAN/ (2) ftp://carroll.cac.psu.edu/pub/CPAN/ (3) ftp://cpan.cse.msu.edu/ ... Select as many URLs as you like, put them on one line, separated by blanks [] 

Make sure you pick more than one since many mirrors have limits on the number of people that can use them at one time. Also, not all mirrors are equally up-to- date. To make the best possible picks, you should visit http://www.mirror.cpan.org, where you can view a profile of each mirror including how up-to-date they are.

The very first thing you should do after configuring the CPAN module is install the newest version of the CPAN module and reload it. You can do that with these commands:

 cpan> install CPAN cpan> reload CPAN 

This will save you the trouble of bumping into bugs in the CPAN module that have been fixed since the version that comes with Perl came out. In particular, older versions of the CPAN module had a nasty habit of trying to upgrade Perl without asking permission. The examples in this book are based on version 1.59_54 of the CPAN module, but using the newest version is always a good idea.

Tip 

If you're having trouble connecting to CPAN using the CPAN module, you might need to manually install the Net::FTP module. See the section that follows on installing modules the hard way for details on how to do this.

After that, your next stop should be the CPAN bundle. The CPAN bundle contains a number of modules that make the CPAN module much easier to use and more robust. To install the bundle, use this command:

 cpan> install Bundle::CPAN 
Note 

See the "Bundles" section later in this chapter to find out how Bundles work.

Now you're ready to install modules. For example, to install the CGI::Application module,[8] you would enter the following command:

 cpan> install CGI::Application 

And the CPAN module will handle downloading the module, running module tests, and installing it. If CGI::Application requires other modules, then the CPAN module will download and install those too.

The CPAN module is versatile tool with myriad options and capabilities. While in the CPAN shell, you can get a description of the available commands using the help command. Also, to learn more about the module itself, you can access the CPAN documentation, using the perldoc utility:

 $ perldoc CPAN 

The Hard Way

The CPAN module may not be right for you. You may be behind a firewall or you might prefer more control over the module installation process. Also, some CPAN modules, usually older ones, aren't written to work with the CPAN module. If this is the case, then you'll need to install modules the hard way. Put on your opaque sunglasses and grab your towel.

Location

First, find the module you want to download on the CPAN server near you. An easy way to do this is by using the CPAN Search facilities described earlier. The file you're looking for will end in either .tar.gz or .zip. CPAN modules have version numbers, and there will usually be a list of versions to choose from. You'll generally want to choose the highest version number available. Download the module file and put it in a working directory on your local machine.

Decompression

These files are compressed, so the first thing you'll need to do is uncompress them to get at their contents. Under UNIX systems this is usually done with the tar and gzip utilities:

 $ gzip -dc ModuleNameHere.tar.gz | tar xvf - 

Under Windows you can use tools such as WinZip, available at http://www.winzip.com, or install a Windows port of the GNU utilities such as CygWin, which includes tar and gzip. CygWin is available at http://www.cygwin.com.

Build

Now that you've unpacked the module, you need to build it. Enter the directory created by unpacking the compressed module file. It's usually named the same as the compressed file but with the .tar.gz or .zip ending removed.

If the module has no installation instructions, look for a file called Makefile.PL. If it exists, enter the following commands:

 $ perl Makefile.PL $ make 

These commands will fail if you're missing a prerequisite module. A prerequisite module is a module that is needed by the module you're installing. If the module has unsatisfied prerequisites, you'll need to find the required module or modules and install them before returning to installing this module.

These commands may also fail if you're using a Microsoft Windows system, because few Windows systems have the make utility installed. You may need to install the CygWin toolkit I mentioned in the "Decompression" section, which offers the GNU make utility as an optional component. Alternately, you may have a program called nmake[9] or dmake, which can function as make.

Regrettably, there are some modules on CPAN that don't use the standard module packaging system. Sometimes these modules will include an INSTALL file containing installation instructions, or installation instructions will be contained in the README file.

Test

Many CPAN modules come with tests to verify that the module is working properly on your system. The standard way to run module tests is with this command:

 $ make test 

Install

Finally, you will need to install the module to be able to use the module in your programs. To do so, enter the following command:

 # make install 

You will need to be root to perform this step on UNIX systems.

[6]There's more than one way to do it.

[7]Written and maintained by Andreas Köenig

[8]Described in Chapter 11

[9]You can download nmake from http://www.download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe.



Writing Perl Modules for CPAN
Writing Perl Modules for CPAN
ISBN: 159059018X
EAN: 2147483647
Year: 2002
Pages: 110
Authors: Sam Tregar

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net