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
    perl modules and extensions. It includes some searching
    capabilities and knows 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
    dedicated directory.

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

    The package contains a session manager and a cache manager.
    There is no status retained between sessions. The session
    manager keeps track of what has been fetched, built and
    installed in the current session. The cache manager keeps track
    of the disk space occupied by the make processes and deletes
    excess space according to a simple FIFO mechanism.

    All methods provided are accessible in a programmer style and in
    an interactive 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
    if you install Term::ReadKey and Term::ReadLine to enjoy both
    history and completion.

    Once you are on the command line, type 'h' and the rest should
    be self-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
      `m' for each of the four categories and another, `i' for any
      of the mentioned four. Each of the four entities is
      implemented as a class with slightly differing methods for
      displaying an object.

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

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

          cpan> a ANDK     
          Author id = ANDK
      	EMAIL        a.koenig@franz.ww.TU-Berlin.DE
      	FULLNAME     Andreas Knig

          cpan> a /andk/   
          Author id = ANDK
      	EMAIL        a.koenig@franz.ww.TU-Berlin.DE
      	FULLNAME     Andreas Knig

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


    make, test, install, clean modules or distributions
      The four commands do indeed exist just as written above. Each
      of them takes as many arguments as provided and investigates
      for each what it might be. Is it a distribution file
      (recognized by embedded slashes), this file is being
      processed. Is it a module, CPAN determines the distribution
      file where this module is included and processes that.

      Any `make' and `test' are run unconditionally. A

        C<install E<lt>distribution_fileE<gt>>


      also is run unconditionally. But for

        C<install E<lt>moduleE<gt>>


      CPAN checks if an install is actually needed for it and prints
      *Foo up to date* in case the module doesnE<39>t need to be
      updated.

      CPAN also keeps track of what it has done within the current
      session and doesnE<39>t try to build a package a second time
      regardless if it succeeded or not. The `force ' command takes
      as first argument the method to invoke (currently: make, test,
      or install) and executes the command from scratch.

      Example:

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


  CPAN::Shell

    The commands that are available in the shell interface are
    methods in the package CPAN::Shell. If you enter the shell
    command, all your input is split by the
    Text::ParseWords::shellwords() routine which acts like most
    shells do. The first word is being interpreted as the method to
    be called and the rest of the words are treated as arguments to
    this method.

  autobundle

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

  recompile

    recompile() is a very special command in that it takes no
    argument and runs the make/test/install cycle with brute force
    over all installed dynamically loadable extensions (aka XS
    modules) with 'force' in effect. Primary purpose of this command
    is to act as a rescue in case your perl breaks binary
    compatibility. If one of the modules that CPAN uses is in turn
    depending on binary compatibility (so you cannot run CPAN
    commands), then you should try the CPAN::Nox module for
    recovery.

    Another popular use for recompile is to finish a network
    installation. Imagine, you have a common source tree for two
    different architectures. You decide to do a completely
    independent fresh installation. You start on one architecture
    with the help of a Bundle file produced earlier. CPAN installs
    the whole Bundle for you, but when you try to repeat the job on
    the second architecture, CPAN responds with a `"Foo up to date"'
    message for all modules. So you will be glad to run recompile in
    the second architecture and youE<39>re done.

  ProgrammerE<39>s interface

    If you do not enter the shell, the available shell commands are
    both available as methods (`CPAN::Shell->install(...)') and as
    functions in the calling package (`install(...)'). The
    programmerE<39>s interface has beta status. Do not heavily rely
    on it, changes may still be necessary.

  Cache Manager

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

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

  Bundles

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

    It starts like a perl module with a package declaration and a
    $VERSION variable. After that the pod section looks like any
    other pod with the only 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
    rest of the line is optional. The comment part is delimited by a
    dash just as in the man page header.

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

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

    There is a meaningless Bundle::Demo available on CPAN. Try to
    install it, it usually does no harm, just demonstrates what the
    Bundle interface looks like.

  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
    run this module. Otherwise Net::FTP is strongly recommended. LWP
    may be required for non-UNIX systems or if your nearest CPAN
    site is associated with an URL that is not `ftp:'.

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

    This module presumes that all packages on CPAN

    * declare their $VERSION variable in an easy to parse manner. This
      prerequisite can hardly be relaxed because it consumes by far
      too much memory to load all packages into the running program
      just to determine the $VERSION variable . Currently all
      programs that are dealing with version 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
      be parsed, please try the above method.

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


  Debugging

    The debugging of this module is pretty difficult, because we
    have interferences of the software producing the indices on
    CPAN, of the mirroring process on CPAN, of packaging, of
    configuration, of synchronicity, and of bugs within CPAN.pm.

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

  Floppy, Zip, and all that Jazz

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

CONFIGURATION
    When the CPAN module is installed a site wide configuration file
    is created as CPAN/Config.pm. The default values defined there
    can be overridden in another configuration file:
    CPAN/MyConfig.pm. You can store 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 the use() or
    require() statements.

    Currently the following keys in the hash reference $CPAN::Config
    are defined:

      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
    cpan shell 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's
      neatvalue 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.


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

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

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

    Future development should be directed towards a better
    intergration of the other parts.

AUTHOR
    Andreas Knig <a.koenig@mind.de>

SEE ALSO
    perl(1), CPAN::Nox(3)

