view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Foo::Bar, i.e. *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.

PREREQUISITES
    The CPAN program is trying to depend on as little as possible so the
    user can use it in hostile environment. It works better the more goodies
    the environment provides. For example if you try in the CPAN shell

      install Bundle::CPAN

    or

      install Bundle::CPANxxl

    you will find the shell more convenient than the bare shell before.

    If you have a local mirror of CPAN and can access all files with "file:"
    URLs, then you only need a perl later 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 a 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.

UTILITIES
  Finding packages and VERSION
    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 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(shift)' 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" or "Build.PL" (well, we try to handle a bit more, but
      with little enthusiasm).

  Debugging
    Debugging this module is more than a bit complex due to interference
    from the software producing the indices on CPAN, the mirroring process
    on CPAN, packaging, configuration, synchronicity, and even (gasp!) due
    to bugs within the CPAN.pm module itself.

    For debugging the code of CPAN.pm itself in interactive mode, some
    debugging aid can be turned on for most packages within CPAN.pm with one
    of

    o debug package...
      sets debug mode for packages.

    o debug -package...
      unsets debug mode for packages.

    o debug all
      turns debugging on for all packages.

    o debug number

    which sets the debugging packages directly. Note that "o debug 0" turns
    debugging off.

    What seems a successful strategy is the combination of "reload cpan" and
    the debugging switches. Add a new debug statement while running in the
    shell and then issue a "reload cpan" and see the new debugging messages
    immediately without losing the current context.

    "o debug" without an argument lists the valid package names and the
    current set of packages in debugging mode. "o debug" has built-in
    completion support.

    For debugging of CPAN data there is the "dump" command which takes the
    same arguments as make/test/install and outputs each object's
    Data::Dumper dump. If an argument looks like a perl variable and
    contains one of "$", "@" or "%", it is eval()ed and fed to Data::Dumper
    directly.

  Floppy, Zip, Offline Mode
    CPAN.pm works nicely without network access, too. If you maintain
    machines that are not networked at all, you should consider working with
    "file:" URLs. You'll 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. See also below the paragraph about CD-ROM support.

  Basic Utilities for Programmers
    has_inst($module)
      Returns true if the module is installed. Used to load all modules into
      the running CPAN.pm that are considered optional. The config variable
      "dontload_list" intercepts the "has_inst()" call such that an optional
      module is not loaded despite being available. For example, the
      following command will prevent "YAML.pm" from being loaded:

          cpan> o conf dontload_list push YAML

      See the source for details.

    use_inst($module)
      Similary to has_inst() tries to load optional library but also dies if
      library is not available