'br}

'br}

{\

## NAME

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 [-cfgimtTw] module_name [ module_name ... ]

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

# without arguments, starts CPAN.pm shell cpan

# dump the configuration cpan -J

# load a different configuration to install Module::Foo cpan -j some/other/file Module::Foo

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

## DESCRIPTION

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

## Options

-a 4

Creates a s-1CPANs0.pm autobundle with CPAN::Shell->autobundle.

-A module [ module ... ] 4

Shows the primary maintainers for the specified modules.

-c module 4

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

-C module [ module ... ] 4

Show the Changes files for the specified modules

-D module [ module ... ] 4

Show the module details.

-f 4

Force the specified action, when it normally would have failed. Use this to install a module even if its tests fail. When you use this option, -i is not optional for installing a module when you need to force it:

% cpan -f -i Module::Foo

-F 4

Turn off s-1CPANs0.pm's attempts to lock anything. You should be careful with this since you might end up with multiple scripts trying to muck in the same directory. This isn't so much of a concern if you're loading a special config with f(CW*(C`-j*(C', and that config sets up its own work directories.

-g module [ module ... ] 4

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

-G module [ module ... ] 4

s-1UNIMPLEMENTEDs0

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

If you want this feature, check out Yanick Champoux's f(CW*(C`Git::CPAN::Patch*(C' distribution.

-h 4

Print a help message and exit. When you specify f(CW*(C`-h*(C', it ignores all of the other options and arguments.

-i 4

Install the specified modules.

-I 4

Load f(CW*(C`local::lib*(C' (think like f(CW*(C`-I*(C' for loading lib paths).

-j Config.pm 4

Load the file that has the s-1CPANs0 configuration data. This should have the same format as the standard CPAN/Config.pm file, which defines f(CW$CPAN::Config as an anonymous hash.

-J 4

Dump the configuration in the same format that s-1CPANs0.pm uses. This is useful for checking the configuration as well as using the dump as a starting point for a new, custom configuration.

-l 4

List all installed modules with their versions

-L author [ author ... ] 4

List the modules by the specified authors.

-m 4

Make the specified modules.

-O 4

Show the out-of-date modules.

-p 4

Ping the configured mirrors

-P 4

Find the best mirrors you could be using (but doesn't configure them just yet)

-r 4

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

-t 4

Run a `make test` on the specified modules.

-T 4

Do not test modules. Simply install them.

-u 4

Upgrade all installed modules. Blindly doing this can really break things, so keep a backup.

-v 4

Print the script version and s-1CPANs0.pm version then exit.

-V 4

Print detailed information about the cpan client.

-w 4

s-1UNIMPLEMENTEDs0

Turn on cpan warnings. This checks various things, like directory permissions, and tells you about problems you might have.

## Examples

# print a help message cpan -h

# print the version numbers cpan -v

# create an autobundle cpan -a

# recompile modules cpan -r

# upgrade all installed modules cpan -u

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

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

## ENVIRONMENT VARIABLES

\s-1CPAN_OPTS\s0 4

f(CW*(C`cpan*(C' splits this variable on whitespace and prepends that list to f(CW@ARGV before it processes the command-line arguments. For instance, if you always want to use f(CW*(C`local:lib*(C', you can set f(CW*(C`CPAN_OPTS*(C' to f(CW*(C`-I*(C'.

## 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

* one shot configuration values from the command line

## BUGS

* none noted

## SEE ALSO

Most behaviour, including environment variables and configuration, comes directly from s-1CPANs0.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, f(CW*(C`<bdfoy@cpan.org>*(C'

## COPYRIGHT

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

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