MAN page from RedHat Other perl-5.004-0.1.i386.rpm

CPAN

Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index

NAME

CPAN - query, download and build perl modules from CPAN sites

SYNOPSIS

Interactive mode:

  perl -MCPAN -e shell;

Batch mode:

  use CPAN;

  autobundle, clean, install, make, recompile, test

DESCRIPTION

The CPAN module is designed to automate the make and install of perlmodules and extensions. It includes some searching capabilities andknows how to use Net::FTP or LWP (or lynx or an external ftp client)to fetch the raw data from the net.

Modules are fetched from one or more of the mirrored CPAN(Comprehensive Perl Archive Network) sites and unpacked in a dedicateddirectory.

The CPAN module also supports the concept of named and versioned'bundles' of modules. Bundles simplify the handling of sets ofrelated modules. See BUNDLES below.

The package contains a session manager and a cache manager. There isno status retained between sessions. The session manager keeps trackof what has been fetched, built and installed in the currentsession. The cache manager keeps track of the disk space occupied bythe make processes and deletes excess space according to a simple FIFOmechanism.

All methods provided are accessible in a programmer style and in aninteractive shell style.

Interactive Mode

The interactive mode is entered by running

    perl -MCPAN -e shell

which puts you into a readline interface. You will have most fun ifyou install Term::ReadKey and Term::ReadLine to enjoy both history andcompletion.

Once you are on the command line, type `h' and the rest should beself-explanatory.

The most common uses of the interactive modes are

Searching for authors, bundles, distribution files and modules

There are corresponding one-letter commands a, b, d, and mfor each of the four categories and another, i for any of thementioned four. Each of the four entities is implemented as a classwith slightly differing methods for displaying an object.

Arguments you pass to these commands are either strings matching exactthe identification string of an object or regular expressions that arethen matched case-insensitively against various attributes of theobjects. The parser recognizes a regualar expression only if youenclose it between two slashes.

The principle is that the number of found objects influences how anitem is displayed. If the search finds one item, we display the resultof object->as_string, but if we find more than one, we displayeach as object->as_glimpse. E.g.

    cpan> a ANDK    Author id = ANDK        EMAIL        a.koenigAATTfranz.ww.TU-Berlin.DE        FULLNAME     Andreas König

    cpan> a /andk/    Author id = ANDK        EMAIL        a.koenigAATTfranz.ww.TU-Berlin.DE        FULLNAME     Andreas König

    cpan> a /and.*rt/    Author          ANDYD (Andy Dougherty)    Author          MERLYN (Randal L. Schwartz)

make, test, install, clean modules or distributions

These commands do indeed exist just as written above. Each of themtakes any number of arguments and investigates for each what it mightbe. Is it a distribution file (recognized by embedded slashes), thisfile is being processed. Is it a module, CPAN determines thedistribution file where this module is included and processes that.

Any make, test, and readme are run unconditionally. A

  install <distribution_file>

also is run unconditionally. But for

  install <module>

CPAN checks if an install is actually needed for it and printsFoo up to date in case the module doesn't need to be updated.

CPAN also keeps track of what it has done within the current sessionand doesn't try to build a package a second time regardless if itsucceeded or not. The force command takes as first argument themethod to invoke (currently: make, test, or install) and executes thecommand from scratch.

Example:

    cpan> install OpenGL    OpenGL is up to date.    cpan> force install OpenGL    Running make    OpenGL-0.4/    OpenGL-0.4/COPYRIGHT    [...]

readme, look module or distribution

These two commands take only one argument, be it a module or adistribution file. readme displays the README of the associateddistribution file. Look gets and untars (if not yet done) thedistribution file, changes to the appropriate directory and opens asubshell process in that directory.

CPAN::Shell

The commands that are available in the shell interface are methods inthe package CPAN::Shell. If you enter the shell command, all yourinput is split by the Text::ParseWords::shellwords() routine whichacts like most shells do. The first word is being interpreted as themethod to be called and the rest of the words are treated as argumentsto this method. Continuation lines are supported if a line ends with aliteral backslash.

autobundle

autobundle writes a bundle file into the$CPAN::Config->{cpan_home}/Bundle directory. The file containsa list of all modules that are both available from CPAN and currentlyinstalled within @INC. The name of the bundle file is based on thecurrent date and a counter.

recompile

recompile() is a very special command in that it takes no argument andruns the make/test/install cycle with brute force over all installeddynamically loadable extensions (aka XS modules) with `force' ineffect. Primary purpose of this command is to finish a networkinstallation. Imagine, you have a common source tree for two differentarchitectures. You decide to do a completely independent freshinstallation. You start on one architecture with the help of a Bundlefile produced earlier. CPAN installs the whole Bundle for you, butwhen you try to repeat the job on the second architecture, CPANresponds with a "Foo up to date" message for all modules. So youwill be glad to run recompile in the second architecture andyou're done.

Another popular use for recompile is to act as a rescue in case yourperl breaks binary compatibility. If one of the modules that CPAN usesis in turn depending on binary compatibility (so you cannot run CPANcommands), then you should try the CPAN::Nox module for recovery.

The four CPAN::* Classes: Author, Bundle, Module, Distribution

Although it may be considered internal, the class hierarchie doesmatter for both users and programmer. CPAN.pm deals with abovementioned four classes, and all those classes share a set ofmethods. It is a classical single polymorphism that is in effect. Ametaclass object registers all objects of all kinds and indexes themwith a string. The strings referencing objects have a separatednamespace (well, not completely separated):

         Namespace                         Class

   words containing a "/" (slash)      Distribution    words starting with Bundle::          Bundle          everything else            Module or Author

Modules know their associated Distribution objects. They always referto the most recent official release. Developers may mark theirreleases as unstable development versions (by inserting an underbarinto the visible version number), so not always is the defaultdistribution for a given module the really hottest and newest. If amodule Foo circulates on CPAN in both version 1.23 and 1.23_90,CPAN.pm offers a convenient way to install version 1.23 by saying

    install Foo

This would install the complete distribution file (sayBAR/Foo-1.23.tar.gz) with all accompanying material in there. But ifyou would like to install version 1.23_90, you need to know where thedistribution file resides on CPAN relative to the authors/id/directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz,so you would have to say

    install BAR/Foo-1.23_90.tar.gz

The first example will be driven by an object of the classCPAN::Module, the second by an object of class CPAN::Distribution.

Programmer's interface

If you do not enter the shell, the available shell commands are bothavailable as methods (CPAN::Shell->install(...)) and asfunctions in the calling package (install(...)).

There's currently only one class that has a stable interface,CPAN::Shell. All commands that are available in the CPAN shell aremethods of the class CPAN::Shell. Each of the commands that producelistings of modules (r, autobundle, u) returns a list of theIDs of all modules within the list.

expand($type,@things)

The IDs of all objects available within a program are strings that canbe expanded to the corresponding real objects with theCPAN::Shell->expand("Module",@things) method. Expand returns alist of CPAN::Module objects according to the @things argumentsgiven. In scalar context it only returns the first element of thelist.

Programming Examples

This enables the programmer to do operations that combinefunctionalities that are available in the shell.

    # install everything that is outdated on my disk:    perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'

    # install my favorite programs if necessary:    for $mod (qw(Net::FTP MD5 Data::Dumper)){        my $obj = CPAN::Shell->expand('Module',$mod);        $obj->install;    }

    # list all modules on my disk that have no VERSION number    for $mod (CPAN::Shell->expand("Module","/./")){        next unless $mod->inst_file;        # MakeMaker convention for undefined $VERSION:        next unless $mod->inst_version eq "undef";        print "No VERSION in ", $mod->id, "\n";    }

Methods in the four

Cache Manager

Currently the cache manager only keeps track of the build directory($CPAN::Config->{build_dir}). It is a simple FIFO mechanism thatdeletes complete directories below build_dir as soon as the size ofall directories there gets bigger than $CPAN::Config->{build_cache}(in MB). The contents of this cache may be used for laterre-installations that you intend to do manually, but will never betrusted by CPAN itself. This is due to the fact that the user mightuse these directories for building modules on different architectures.

There is another directory ($CPAN::Config->{keep_source_where}) wherethe original distribution files are kept. This directory is notcovered by the cache manager and must be controlled by the user. Ifyou choose to have the same directory as build_dir and askeep_source_where directory, then your sources will be deleted withthe same fifo mechanism.

Bundles

A bundle is just a perl module in the namespace Bundle:: that does notdefine any functions or methods. It usually only contains documentation.

It starts like a perl module with a package declaration and a $VERSIONvariable. After that the pod section looks like any other pod with theonly difference, that one special pod section exists starting with(verbatim):

        =head1 CONTENTS

In this pod section each line obeys the format

        Module_Name [Version_String] [- optional text]

The only required part is the first field, the name of a module(eg. Foo::Bar, ie. not the name of the distribution file). The restof the line is optional. The comment part is delimited by a dash justas in the man page header.

The distribution of a bundle should follow the same convention asother distributions.

Bundles are treated specially in the CPAN package. If you say `installBundle::Tkkit' (assuming such a bundle exists), CPAN will install allthe modules in the CONTENTS section of the pod. You can install yourown Bundles locally by placing a conformant Bundle file somewhere intoyour @INC path. The autobundle() command which is available in theshell interface does that for you by including all currently installedmodules in a snapshot bundle file.

Prerequisites

If you have a local mirror of CPAN and can access all files with``file:'' URLs, then you only need a perl better than perl5.003 to runthis module. Otherwise Net::FTP is strongly recommended. LWP may berequired for non-UNIX systems or if your nearest CPAN site isassociated with an URL that is not ftp:.

If you have neither Net::FTP nor LWP, there is a fallback mechanismimplemented for an external ftp command or for an external lynxcommand.

This module presumes that all packages on CPAN

•

declare their $VERSION variable in an easy to parse manner. Thisprerequisite can hardly be relaxed because it consumes by far too muchmemory to load all packages into the running program just to determinethe $VERSION variable . Currently all programs that are dealing withversion use something like this

    perl -MExtUtils::MakeMaker -le \        'print MM->parse_version($ARGV[0])' filename

If you are author of a package and wonder if your $VERSION can beparsed, please try the above method.

•

come as compressed or gzipped tarfiles or as zip files and contain aMakefile.PL (well we try to handle a bit more, but without muchenthusiasm).

Debugging

The debugging of this module is pretty difficult, because we haveinterferences of the software producing the indices on CPAN, of themirroring process on CPAN, of packaging, of configuration, ofsynchronicity, and of bugs within CPAN.pm.

In interactive mode you can try ``o debug'' which will list options fordebugging the various parts of the package. The output may not be veryuseful for you as it's just a byproduct of my own testing, but if youhave an idea which part of the package may have a bug, it's sometimesworth to give it a try and send me more specific output. You shouldknow that ``o debug'' has built-in completion support.

Floppy, Zip, and all that Jazz

CPAN.pm works nicely without network too. If you maintain machinesthat are not networked at all, you should consider working with file:URLs. Of course, you have to collect your modules somewhere first. Soyou might use CPAN.pm to put together all you need on a networkedmachine. Then copy the $CPAN::Config->{keep_source_where} (but not$CPAN::Config->{build_dir}) directory on a floppy. This floppy is kindof a personal CPAN. CPAN.pm on the non-networked machines works nicelywith this floppy.

CONFIGURATION

When the CPAN module is installed a site wide configuration file iscreated as CPAN/Config.pm. The default values defined there can beoverridden in another configuration file: CPAN/MyConfig.pm. You canstore this file in $HOME/.cpan/CPAN/MyConfig.pm if you want, because$HOME/.cpan is added to the search path of the CPAN module before theuse() or require() statements.

Currently the following keys in the hash reference $CPAN::Config aredefined:

  build_cache        size of cache for directories to build modules  build_dir          locally accessible directory to build modules  index_expire       after how many days refetch index files  cpan_home          local directory reserved for this package  gzip               location of external program gzip  inactivity_timeout breaks interactive Makefile.PLs after that                     many seconds inactivity. Set to 0 to never break.  inhibit_startup_message                     if true, does not print the startup message  keep_source        keep the source in a local directory?  keep_source_where  where keep the source (if we do)  make               location of external program make  make_arg           arguments that should always be passed to 'make'  make_install_arg   same as make_arg for 'make install'  makepl_arg         arguments passed to 'perl Makefile.PL'  pager              location of external program more (or any pager)  tar                location of external program tar  unzip              location of external program unzip  urllist            arrayref to nearby CPAN sites (or equivalent locations)

You can set and query each of these options interactively in the cpanshell with the command set defined within the o conf command:

o conf <scalar option>: prints the current value of the scalar option
o conf <scalar option> <value>: Sets the value of the scalar option to value
o conf <list option>: prints the current value of the list option in MakeMaker'sneatvalue format.
o conf <list option> [shift|pop]: shifts or pops the array in the list option variable
o conf <list option> [unshift|push|splice] <list>: works like the corresponding perl commands.

CD-ROM support

The urllist parameter of the configuration table contains a list ofURLs that are to be used for downloading. If the list contains anyfile URLs, CPAN always tries to get files from there first. Thisfeature is disabled for index files. So the recommendation for theowner of a CD-ROM with CPAN contents is: include your local, possiblyoutdated CD-ROM as a file URL at the end of urllist, e.g.

  o conf urllist push file://localhost/CDROM/CPAN

CPAN.pm will then fetch the index files from one of the CPAN sitesthat come at the beginning of urllist. It will later check for eachmodule if there is a local copy of the most recent version.

SECURITY

There's no strong security layer in CPAN.pm. CPAN.pm helps you toinstall foreign, unmasked, unsigned code on your machine. We compareto a checksum that comes from the net just as the distribution fileitself. If somebody has managed to tamper with the distribution file,they may have as well tampered with the CHECKSUMS file. Futuredevelopment will go towards strong authentification.

EXPORT

Most functions in package CPAN are exported per default. The reasonfor this is that the primary use is intended for the cpan shell or foroneliners.

BUGS

we should give coverage for _all_ of the CPAN and not just thePAUSE part, right? In this discussion CPAN and PAUSE have becomeequal -- but they are not. PAUSE is authors/ and modules/. CPAN isPAUSE plus the clpa/, doc/, misc/, ports/, src/, scripts/.

Future development should be directed towards a better integration ofthe other parts.

AUTHOR

Andreas König <a.koenigAATTmind.de>

This document was created byman2html,using the manual pages.