1.3.1.1. Configuring

If you have never used the CPAN shell, you will need to configure itbefore you can use it. It will prompt you for some information beforebuilding its configuration file.

Invoke the CPAN shell by entering the following command at a systemshell prompt:

% perl -MCPAN -eshell

If you've never run it before,you'll see this:

We have to reconfigure CPAN.pm due to following uninitialized parameters:

followed by a number of questions. For each question, the defaultanswer is typically fine, but you may answer otherwise if you knowthat the default setting is wrong or not optimal. Onceyou've answered all the questions, a configurationfile is created and you can start working with the CPAN shell.

1.3.1.2. Obtaining help

If you need help at any time, you can read the CPANshell's manual page by typingperldoc CPAN or by starting upthe CPAN shell (with perl-MCPAN -eshell at a systemshell prompt) and entering h at thecpan> prompt:

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

1.3.1.3. Installing LWP

All you have to do is enter:

cpan> install Bundle::LWP

The CPAN shell will show messages explaining whatit's up to. You may need to answer questions toconfigure the various modules (e.g., libnet asks for mail hosts andso on for testing purposes).

After much activity, you should then have a fresh copy of LWP on yoursystem, with far less work than installing it manually onedistribution at a time. At the time of this writing, installBundle::LWP installs not just the libwww-perl distribution,but also URI and HTML-Parser. It does not install the HTML-Treedistribution that we'll use in Chapter 9, "HTML Processing with Trees" and Chapter 10, "Modifying HTML with Trees". To do that,enter:

cpan> install HTML::Tree

These commands do not install the HTML-Format distribution, which wasalso once part of the LWP distribution. I do not discuss HTML-Formatin this book, but if you want to install it so that you have acomplete LWP installation, enter this command:

cpan> install HTML::Format

Remember, LWP may be just about the most popular distribution inCPAN, but that's not all there is! Look around theweb-related parts of CPAN (I prefer the interface at http://search.cpan.org, but you can also tryhttp://kobesearch.cpan.org) asthere are dozens of modules, from WWW::Automate to SOAP::Lite, thatcan simplify your web-related tasks.

1.3.2.1. Download distributions

First, download the moduledistributions.LWP requires several other modules to operate successfully.You'll need to install the distributions given inTable 1-1, in the order in which they are listed.

Table 1-1. Modules used in this book

Fetch these modules from one of the FTP or web sites that form CPAN,listed at http://www.cpan.org/SITES.html andhttp://mirror.cpan.org. SometimesCPAN has several versions of a module in theauthors directory. Be sure to check the versionnumber and get the latest.This book is about the latest version of LWP! Upgrade now!

For example to install MIME-Base64, you might first fetch http://www.cpan.org/authors/id/G/GA/GAAS/ tosee which versions are there, then fetch http://www.cpan.org/authors/id/G/GA/GAAS/MIME-Base64-2.12.tar.gzand install that.

1.3.2.2. Unpack and configure

The distributions are gzipped tar archives of source code.Extracting a distribution creates a directory, and in that directoryis a Makefile.PL Perl program that builds aMakefile for you.

% tar xzf MIME-Base64-2.12.tar.gz
% cd MIME-Base64-2.12
% perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for MIME::Base64

1.3.2.3. Make, test, and install

Compile the code with the make command:

% make
cp Base64.pm blib/lib/MIME/Base64.pm
cp QuotedPrint.pm blib/lib/MIME/QuotedPrint.pm
/usr/bin/perl -I/opt/perl5/5.6.1/i386-freebsd -I/opt/perl5/5.6.1
/opt/perl5/5.6.1/ExtUtils/xsubpp  -typemap
/opt/perl5/5.6.1/ExtUtils/typemap Base64.xs > Base64.xsc && mv
  Base64.xsc Base64.c
cc -c  -fno-strict-aliasing -I/usr/local/include -O    -DVERSION=\"2.12\"
  -DXS_VERSION=\"2.12\" -DPIC -fpic -I/opt/perl5/5.6.1/i386-freebsd/CORE
Base64.c
Running Mkbootstrap for MIME::Base64 ( )
chmod 644 Base64.bs
rm -f blib/arch/auto/MIME/Base64/Base64.so
LD_RUN_PATH="" cc -o blib/arch/auto/MIME/Base64/Base64.so  -shared
  -L/opt Base64.o
chmod 755 blib/arch/auto/MIME/Base64/Base64.so
cp Base64.bs blib/arch/auto/MIME/Base64/Base64.bs
chmod 644 blib/arch/auto/MIME/Base64/Base64.bs
Manifying blib/man3/MIME::Base64.3
Manifying blib/man3/MIME::QuotedPrint.3

Then make sure everything works on your system with maketest:

% make test
PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib 
-I/opt/perl5/5.6.1/i386-freebsd -I/opt/perl5/5.6.1 -e 'use Test::Harness
  qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
t/base64..........ok
t/quoted-print....ok
t/unicode.........skipped test on this platform
All tests successful, 1 test skipped.
Files=3, Tests=306,  1 wallclock secs ( 0.52 cusr +  0.06 csys =  0.58 CPU)

If it passes the tests, install it with makeinstall (as the superuser):

# make install
Installing /opt/perl5/site_perl/5.6.1/i386-freebsd/auto/MIME/Base64/Base64.so
Installing /opt/perl5/site_perl/5.6.1/i386-freebsd/auto/MIME/Base64/Base64.bs
Files found in blib/arch: installing files in blib/lib into architecture
  dependent library tree
Installing /opt/perl5/site_perl/5.6.1/i386-freebsd/MIME/Base64.pm
Installing /opt/perl5/site_perl/5.6.1/i386-freebsd/MIME/QuotedPrint.pm
Installing /usr/local/man/man3/MIME::Base64.3
Installing /usr/local/man/man3/MIME::QuotedPrint.3
Writing /opt/perl5/site_perl/5.6.1/i386-freebsd/auto/MIME/Base64/.packlist
Appending installation info to /opt/perl5/5.6.1/i386-freebsd/perllocal.pod