/ 
App-Cpan-1.56_01
/ App::Cpan

NAME

App::Cpan - easily interact with CPAN from the command line

SYNOPSIS

# with arguments and no switches, installs specified modules
cpan module_name [ module_name ... ]

# with switches, installs modules with extra behavior
cpan [-cfimt] module_name [ module_name ... ]

# with just the dot, install from the distribution in the
# current directory
cpan .

# without arguments, starts CPAN.pm shell
cpan

# without arguments, but some switches
cpan [-ahrvACDLO]

DESCRIPTION

This script provides a command interface (not a shell) to CPAN. At the moment it uses CPAN.pm to do the work, but it is not a one-shot command runner for CPAN.pm.

Meta Options

These options are mutually exclusive, and the script processes them in this order: [hvCAar]. Once the script finds one, it ignores the others, and then exits after it finishes the task. The script ignores any other command line options.

-a

Creates the CPAN.pm autobundle with CPAN::Shell->autobundle.

-A module [ module ... ]

Shows the primary maintainers for the specified modules

-C module [ module ... ]

Show the Changes files for the specified modules

-D module [ module ... ]

Show the module details. This prints one line for each out-of-date module (meaning, modules locally installed but have newer versions on CPAN). Each line has three columns: module name, local version, and CPAN version.

-g module [ module ... ]

Downloads to the current directory the latest distribution of the module.

-G module [ module ... ]

UNIMPLEMENTED

Downloads to the current directory the latest distribution of the module, unpack each distribution, and create a git repository for each distribution.

-j Config.pm

Load the file that has the CPAN configuration data. This should have the same format as the standard CPAN/Config.pm file, which defines $CPAN::Config as an anonymous hash.

-J

Dump the configuration in the same format that CPAN.pm uses.

-L author [ author ... ]

List the modules by the specified authors.

-h

Prints a help message.

-O

Show the out-of-date modules.

-r

Recompiles dynamically loaded modules with CPAN::Shell->recompile.

-v

Print the script version and CPAN.pm version.

Module options

These options are mutually exclusive, and the script processes them in alphabetical order. It only processes the first one it finds.

c

Runs a `make clean` in the specified module's directories.

f

Forces the specified action, when it normally would have failed.

i

Installed the specified modules.

m

Makes the specified modules.

t

Runs a `make test` on the specified modules.

Examples

# print a help message
cpan -h

# print the version numbers
cpan -v

# create an autobundle
cpan -a

# recompile modules
cpan -r

# install modules ( sole -i is optional )
cpan -i Netscape::Booksmarks Business::ISBN

# force install modules ( must use -i )
cpan -fi CGI::Minimal URI

Methods

run()

Just do it.

The run method returns 0 on success and a postive number on failure. See the section on EXIT CODES for details on the values.

CPAN.pm sends all the good stuff either to STDOUT, or to a temp file if $CPAN::Be_Silent is set. I have to intercept that output so I can find out what happened.

EXIT VALUES

The script exits with zero if it thinks that everything worked, or a positive number if it thinks that something failed. Note, however, that in some cases it has to divine a failure by the output of things it does not control. For now, the exit codes are vague:

1	An unknown error

2	The was an external problem

4	There was an internal problem with the script

8	A module failed to install

TO DO

* There is initial support for Log4perl if it is available, but I haven't gone through everything to make the NullLogger work out correctly if Log4perl is not installed.

* When I capture CPAN.pm output, I need to check for errors and report them to the user.

BUGS

* none noted

SEE ALSO

Most behaviour, including environment variables and configuration, comes directly from CPAN.pm.

SOURCE AVAILABILITY

This code is in Github:

git://github.com/briandfoy/cpan_script.git

CREDITS

Japheth Cleaver added the bits to allow a forced install (-f).

Jim Brandt suggest and provided the initial implementation for the up-to-date and Changes features.

Adam Kennedy pointed out that exit() causes problems on Windows where this script ends up with a .bat extension

AUTHOR

brian d foy, <bdfoy@cpan.org>

COPYRIGHT

Copyright (c) 2001-2008, brian d foy, All Rights Reserved.

You may redistribute this under the same terms as Perl itself.