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 as well knows a how to use Net::FTP or LWP 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 in a simple FIFO style.

    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 other 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. An `install
      <distribution_file>' also is run unconditionally. But for
      `install <module<gt'> CPAN checks if an install is actually
      needed for it and prints *"Foo 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
      session and doesn'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.

  Programmer'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
    programmer's interface has beta status. Do not heavily rely on
    it, changes may still happen.

  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. The bundle() function in the CPAN module
    simply parses the module that defines the bundle and returns the
    module names that are listed in the described CONTENTS section.

    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.

  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.

    A very 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 you're done.

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
      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. Whitespace is used
      to determine the arguments.


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 stong
    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.

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.

  Prerequisites

    If you have a local mirror of CPAN and can access all files with
    "file:" URLs, then you only need perl5.003 to run this module.
    Otherwise you need Net::FTP intalled. LWP may be required for
    non-UNIX systems or if your nearest CPAN site is associated with
    an URL that is not `ftp:'.

    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).


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

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

