cpan(1) - f14

1CPAN(1)                Perl Programmers Reference Guide                CPAN(1)
2
3
4

NAME

6       cpan - easily interact with CPAN from the command line
7

SYNOPSIS

9               # with arguments and no switches, installs specified modules
10               cpan module_name [ module_name ... ]
11
12               # with switches, installs modules with extra behavior
13               cpan [-cfgimt] module_name [ module_name ... ]
14
15               # with just the dot, install from the distribution in the
16               # current directory
17               cpan .
18
19               # without arguments, starts CPAN.pm shell
20               cpan
21
22               # dump the configuration
23               cpan -J
24
25               # load a different configuration to install Module::Foo
26               cpan -j some/other/file Module::Foo
27
28               # without arguments, but some switches
29               cpan [-ahrvACDlLO]
30

DESCRIPTION

32       This script provides a command interface (not a shell) to CPAN. At the
33       moment it uses CPAN.pm to do the work, but it is not a one-shot command
34       runner for CPAN.pm.
35
36   Options
37       -a  Creates a CPAN.pm autobundle with CPAN::Shell->autobundle.
38
39       -A module [ module ... ]
40           Shows the primary maintainers for the specified modules.
41
42       -c module
43           Runs a `make clean` in the specified module's directories.
44
45       -C module [ module ... ]
46           Show the Changes files for the specified modules
47
48       -D module [ module ... ]
49           Show the module details. This prints one line for each out-of-date
50           module (meaning, modules locally installed but have newer versions
51           on CPAN).  Each line has three columns: module name, local version,
52           and CPAN version.
53
54       -f  Force the specified action, when it normally would have failed. Use
55           this to install a module even if its tests fail. When you use this
56           option, -i is not optional for installing a module when you need to
57           force it:
58
59                   % cpan -f -i Module::Foo
60
61       -F  Turn off CPAN.pm's attempts to lock anything. You should be careful
62           with this since you might end up with multiple scripts trying to
63           muck in the same directory. This isn't so much of a concern if
64           you're loading a special config with "-j", and that config sets up
65           its own work directories.
66
67       -g module [ module ... ]
68           Downloads to the current directory the latest distribution of the
69           module.
70
71       -G module [ module ... ]
72           UNIMPLEMENTED
73
74           Download to the current directory the latest distribution of the
75           modules, unpack each distribution, and create a git repository for
76           each distribution.
77
78           If you want this feature, check out Yanick Champoux's
79           "Git::CPAN::Patch" distribution.
80
81       -h  Print a help message and exit. When you specify "-h", it ignores
82           all of the other options and arguments.
83
84       -i  Install the specified modules.
85
86       -j Config.pm
87           Load the file that has the CPAN configuration data. This should
88           have the same format as the standard CPAN/Config.pm file, which
89           defines $CPAN::Config as an anonymous hash.
90
91       -J  Dump the configuration in the same format that CPAN.pm uses. This
92           is useful for checking the configuration as well as using the dump
93           as a starting point for a new, custom configuration.
94
95       -L author [ author ... ]
96           List the modules by the specified authors.
97
98       -m  Make the specified modules.
99
100       -O  Show the out-of-date modules.
101
102       -t  Run a `make test` on the specified modules.
103
104       -r  Recompiles dynamically loaded modules with CPAN::Shell->recompile.
105
106       -v  Print the script version and CPAN.pm version then exit.
107
108   Examples
109               # print a help message
110               cpan -h
111
112               # print the version numbers
113               cpan -v
114
115               # create an autobundle
116               cpan -a
117
118               # recompile modules
119               cpan -r
120
121               # install modules ( sole -i is optional )
122               cpan -i Netscape::Booksmarks Business::ISBN
123
124               # force install modules ( must use -i )
125               cpan -fi CGI::Minimal URI
126

EXIT VALUES

128       The script exits with zero if it thinks that everything worked, or a
129       positive number if it thinks that something failed. Note, however, that
130       in some cases it has to divine a failure by the output of things it
131       does not control. For now, the exit codes are vague:
132
133               1       An unknown error
134
135               2       The was an external problem
136
137               4       There was an internal problem with the script
138
139               8       A module failed to install
140

TO DO

142       * one shot configuration values from the command line
143

BUGS

145       * none noted
146

SOURCE AVAILABILITY

152       This code is in Github:
153
154               git://github.com/briandfoy/cpan_script.git
155

CREDITS

157       Japheth Cleaver added the bits to allow a forced install (-f).
158
159       Jim Brandt suggest and provided the initial implementation for the up-
160       to-date and Changes features.
161
162       Adam Kennedy pointed out that exit() causes problems on Windows where
163       this script ends up with a .bat extension
164

AUTHOR

166       brian d foy, "<bdfoy@cpan.org>"
167

COPYRIGHT

169       Copyright (c) 2001-2009, brian d foy, All Rights Reserved.
170
171       You may redistribute this under the same terms as Perl itself.
172
173
174
175perl v5.12.4                      2011-11-04                           CPAN(1)