NAME

CPANPLUS - Command-line access to the CPAN interface

SYNOPSIS

    cpanp
    cpanp -i Some::Module

    perl -MCPANPLUS -eshell
    perl -MCPANPLUS -e'fetch Some::Module'

    ### for programmatic interfacing, see below ###

DESCRIPTION

The CPANPLUS library is an API to the CPAN mirrors and a collection of interactive shells, commandline programs, daemons, etc, that use this API.

This documentation will discuss all of these briefly and direct you to the appropriate tool to use for the job at hand.

INTERFACES

COMMAND LINE

The CPANPLUS library comes with several command line tools;

cpanp

This is the commandline tool to start the default interactive shell (see SHELLS below), or to do one-off commands. See cpanp -h for details.

cpan2dist.pl

This is a commandline tool to convert any distribution from CPAN into a package in the format of your choice, like for example .deb or FreeBSD ports. See cpan2dist.pl -h for details.

cpanpd.pl

This is a daemon that acts as a remote backend to your default shell. This allows you to administrate multiple perl installations on multiple machines using only one frontend. See cpanpd.pl -h for details.

SHELLS

Interactive shells are there for when you want to do multiple queries, browse the CPAN mirrors, consult a distributions README, etc.

The CPANPLUS library comes with a variety of possible shells. You can install third party shells from the CPAN mirrors if the default one is not to your liking.

CPANPLUS::Shell::Default

This is the standard shell shipped with CPANPLUS. The commands

    cpanp

and

    perl -MCPANPLUS -eshell

should fire it up for you. Type h at the prompt to see how to use it.

CPANPLUS::Shell::Classic

This is the emulation shell that looks and feels just like the old CPAN.pm shell.

API

All the above tools are written using the CPANPLUS API. If you have any needs that aren't already covered by the above tools, you might consider writing your own. To do this, use the CPANPLUS::Backend module. It implements the full CPANPLUS API.

Consult the CPANPLUS::Backend documentation on how to use it.

PLUGINS

There are various plugins available for CPANPLUS. Below is a short listing of just a few of these plugins;

Various shells

As already available in the 0.04x series, CPANPLUS provides various shells (as described in the SHELL section above). There are also 3rd party shells you might get from a cpan mirror near you, such as:

CPANPLUS::Shell::Curses

A shell using libcurses

CPANPLUS::Shell::Tk

A shell using the graphical toolkit Tk

Various package manager plugins

As already available in the 0.04x series, CPANPLUS can provide a hook to install modules via the package manager of your choice. Look in the CPANPLUS::Dist:: namespace on cpan to see what's available. Installing such a plugin will allow you to create packages of that type using the cpan2dist program provided with CPANPLUS or by saying, to create for example, debian distributions:

    cpanp -i Acme::Bleach --format=debian

There are a few package manager plugins available and/or planned already; they include, but are not limited to:

CPANPLUS::Dist::Ports

Allows you to create packages for FreeBSD ports.

CPANPLUS::Dist::Deb

Allows you to create .deb packages for Debian linux.

CPANPLUS::Dist::MDK

Allows you to create packages for MandrakeLinux.

CPANPLUS::Dist::PPM

Allows you to create packages in the PPM format, commonly used by ActiveState Perl.

CPANPLUS Remote Daemon

New in the 0.05x series is the CPANPLUS Daemon. This application allows you to remotely control several machines running the CPANPLUS Daemon, thus enabling you to update several machines at once, or updating machines from the comfort of your own desktop. This is done using CPANPLUS::Shell::Default's dispatch_on_input method. See the CPANPLUS::Shell::Default manpage for details on that method.

Scriptable Shell

New in the 0.05x series is the possibility of scripting the default shell. This can be done by using its dispatch_on_input method. See the CPANPLUS::Shell::Default manpage for details on that method.

Also, soon it will be possible to have a .rc file for the default shell, making aliases for all your commonly used functions. For exmpale, you could alias 'd' to do this:

    d --fetchdir=/my/downloads

or you could make the re-reading of your sourcefiles force a refetch of those files at all times: x --update_source

FUNCTIONS

For quick access to common commands, you may use this module, CPANPLUS rather than the full programmatic API situated in CPANPLUS::Backend. This module offers the following functions:

install(NAME)

This function requires the full name of the module, which is case sensitive. The module name can also be provided as a fully qualified file name, beginning with a /, relative to the /authors/id directory on a CPAN mirror.

It will download, extract and install the module.

fetch(NAME)

Like install, fetch needs the full name of a module or the fully qualified file name, and is case sensitive.

It will download the specified module to the current directory.

get(NAME)

Get is provided as an alias for fetch for compatibility with CPAN.pm.

shell

Shell starts the default CPAN shell. You can also start the shell by using the cpanp command, which will be installed in your perl bin.

See CPANPLUS::Shell::Default for instructions on using the default shell. Note that if you have changed your default shell in your configuration, that shell will be used instead. If for some reason there was an error with your specified shell, you will be given the default shell.

You may also optionally specify another shell to use for this invocation (which is a good way to test other shells): perl -MCPANPLUS -e 'shell Classic'

Shells are only designed to be used on the command-line; use of shells for scripting is discouraged and completely unsupported.

FAQ

For frequently asked questions and answers, please consult the CPANPLUS::FAQ manual.

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

The CPAN++ interface (of which this module is a part of) is copyright (c) 2001, 2002, 2003, 2004, 2005 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

Please see the AUTHORS file in the CPANPLUS distribution for a list of Credits and Contributors.

SEE ALSO

CPANPLUS::Backend, CPANPLUS::Shell::Default, CPANPLUS::FAQ, cpanp, cpan2dist.pl

CONTACT INFORMATION

• General suggestions: cpanplus-info@lists.sourceforge.net

• Bug reporting: cpanplus-bugs@lists.sourceforge.net

• Development list: cpanplus-devel@lists.sourceforge.net

cpanm CPANPLUS

perl -MCPAN -e shell
install CPANPLUS