Installing the Modules Under...

Installing the Modules Under

For each of the examples in the following sections, you will attempt to install the Date::Manip module from CPAN. To install your own module or bundle, simply substitute the name of your module in place of Date::Manip .

Windows

With Windows, the easiest solution is to use prepackaged modules available from ActiveState Tool Corp., assuming , of course, that the Perl installation you have is from ActiveState.

To install a prebuilt module under Windows, you first need to start the Perl Package Manager (PPM). This utility simplifies the module-building process for you by providing an interactive interface to module installation. To start the PPM, you need to open a DOS command prompt, as shown in Figure A.1; you should be connected to the Internet.

Figure A.1. You can work from the DOS command prompt.

At the command prompt, simply type ppm , as shown here. The PPM utility should then start; if it doesn't, you need to look for the ppm.bat file that was installed with ActiveState Perl and run it with the full pathname.

 C:\Windows>  ppm  PPM interactive shell (2.1.6) - type 'help' for available commands PPM> 

To search for a particular module, use the search command, as shown here. You need to use this command because ActiveState doesn't have prebuilt packages for all the modules in CPAN, only the more requested ones. Also, for installation, you have to be able to spell the name of the module correctly.

 PPM>  search Date  Packages available from http://www.ActiveState.com/packages:         Date-Calc         Date-Manip         TimeDate PPM> 

I've summarized the results of the search. There are actually more than 40 available date modules. After you've found the module you want ” Date-Manip for this example ”you can install it by using the install command, as follows :

 PPM>  install Date-Manip  Install package 'Date-Manip?' (y/N):  y  Installing C:\Perl\html\lib\Date\Manip.html Installing C:\Perl\htmlhelp\pkg-Date-Manip.chm Installing C:\Perl\htmlhelp\pkg-Date-Manip.hhc Installing C:\Perl\site\lib\Date\Manip.pm Writing C:\Perl\site\lib/auto/Date-Manip/.packlist PPM> 

The Date::Manip module is now installed!

If you want to download the bundle and install it manually ”perhaps the PC doesn't have Internet access or is behind a firewall ”you can find instructions for downloading and installing modules by hand and dealing with firewalls on ActiveState's Web site (http://www.ActiveState.com). ActiveState maintains a FAQ specific to its distribution of Perl, and you can find the necessary instructions there.

By the Way

Installing modules without PPM ”for example, using your own C compiler under Microsoft Windows ”is well beyond the scope of this book. The source distribution of Perl contains instructions for building Perl yourself under Windows, but this job is not for beginners . If you can accomplish that, building modules for yourself shouldn't be too difficult because the processes are about the same.

UNIX, Using CPAN

Installing modules under UNIX can be exciting and full of challenges, or it can be ridiculously easy. You need an ANSI C compiler (the one used to build Perl will be fine) and a compiler license if your vendor requires one. You also need a copy of the GNU compression program gzip/gunzip; some UNIX vendors ship it as a standard utility. You can obtain a copy from http://www.fsf.org if you don't have it.

One last thing: You'll probably need root privileges on the installation machine. Normally, Perl is installed as a systemwide utility. Installing modules into the system directories requires that you have adequate permission to do so ”root permission.

The Perl installation comes with a module called CPAN that is designed to help you install other modules. To get the installation started, you start Perl using the CPAN module's shell like this:

 $  perl -MCPAN -e shell  

The first time you run this command, the CPAN module interrogates you to find out where you want to fetch Perl modules from and how you want them built. Most of the time, the default answers are sufficient. You are asked about the location of temporary directories, which CPAN mirror you want to use (a list is presented), and whether you're accessing the Internet through a proxy.

When CPAN is done interrogating you, you are presented with this prompt:

 cpan shell -- CPAN exploration and modules installation (v1.3901) ReadLine support available (try [ag][ag]install Bundle::CPAN'') cpan> 

At this prompt, you can use the command i / pat / to search for information on a package, where pat specifies the pattern to search for. To find the Date::Manip module, for example, search like this:

 cpan>  i /Manip/  

The CPAN module may need to contact a CPAN server and obtain a new copy of the index. This situation happens only when needed, and the process takes just a moment. When the query is done, CPAN replies with something like the following information:

 Distribution    SBECK/DateManip-5.35.tar.gz Module          Date::Manip     (SBECK/DateManip-5.35.tar.gz) 

To install the module, type the following:

 cpan>  install Date::Manip  

Now, the CPAN module goes through the process of fetching, compiling, testing, and installing the module for you. The display is quite messy but looks something like this greatly abbreviated example (# comments normally do not appear, they're added for clarity here):

 Running make for SBECK/DateManip-5.35.tar.gz Fetching with LWP:            # Fetching the module ftp://ftp.perl.org/pub/perl/CPAN/authors/id/SBECK/DateManip-5.35.t ar.gz Writing Makefile for Date::Manip mkdir blib                    # Building the module mkdir blib/lib Target "makemakerdflt" is up to date.   /usr/bin/make  -- OK Running make test             # Testing to ensure it works         PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib -I/usr/local/lib/ perl5/5.00502/aix -I/usr/local/lib/perl5/5.00502 -e 'use Test::Harness qw(&runte sts $verbose); $verbose=0; runtests @ARGV;' t/*.t t/settime...........ok t/unixdate..........ok All tests successful. Files=30,  Tests=826, 178 wallclock secs (168.85 cusr +  5.23 csys = 174.08 CPU) Target "test" is up to date.   /usr/bin/make test -- OK Running make install          # Installing the module Target "install" is up to date.    /usr/bin/make install  -- OK 

Your output will vary considerably from the preceding . The module is now tested and installed. Enjoy!

UNIX, The Hard Way

Although you can install modules in UNIX without using the CPAN module, most of the time you don't need to install this way. This method is presented for completeness only; you should really use the CPAN module whenever possible.

First, you need to download the module from CPAN. It is a gzip'ed tar bundle. If the module is Date::Calc , for example, you would need to obtain the latest version, which has a name something like Date-Calc-X.Y.tar.gz. After you've downloaded the bundle, go to that directory and unpack the bundle like this:

 $  gunzip Date-Calc-4_2.tar.gz  $  tar xf Date-Calc-4_2.tar  

Unpacking creates a subdirectory called Date-Calc-4.2. Change into that subdirectory by using cd , and type the following command:

 $  perl Makefile.PL  Checking if your kit is complete... Looks good Writing Makefile for Date::Calc 

Now you have a makefile, which is required for the build process. Next , build the module by using the make command as follows:

 $  make  mkdir blib mkdir blib/lib : Manifying blib/man3/Date::Calc.3 Target "makemakerdflt" is up to date. 

This process might take awhile.

At the next prompt, you need to test the module to see whether it is built correctly. Just type make test as follows:

 $  make test  PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib -I/usr/local/lib/ perl5/5.00502/aix -I/usr/local/lib/perl5/5.00502 -e 'use Test::Harness qw(&runte sts $verbose); $verbose=0; runtests @ARGV;' t/*.t t/f000..............ok t/f001..............ok : t/f032..............ok t/f033..............ok All tests successful. Files=34,  Tests=1823, 14 wallclock secs ( 9.81 cusr +  1.10 csys = 10.91 CPU) Target "test" is up to date. 

You should always run the make test command to ensure the module was built correctly. It can save you (and others) hours of debugging later. When the test is complete, you need to install the module, as shown here. This step is usually done as the root user because the installation must write to system directories.

 $  su  Password:  *******  #  make install  Installing /usr/local/lib/perl5/site_perl/5.005/aix/auto/Date/Calc/Calc.so : Appending installation info to /usr/local/lib/perl5/5.00502/aix/perllocal.pod Target "install" is up to date. # 

At this point, you're done!

Mac OS X

As noted earlier in this book, under the hood Mac OS X is essentially Unix. Use the instructions from Hour 1, "Getting Started with Perl," to get to a prompt, and then follow the Unix instructions for installing modules.