cpan(1) - f39

1CPAN(1)               User Contributed Perl Documentation              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 [-cfFimtTw] module_name [ module_name ... ]
14
15               # use local::lib
16               cpan -I module_name [ module_name ... ]
17
18               # one time mirror override for faster mirrors
19               cpan -p ...
20
21               # with just the dot, install from the distribution in the
22               # current directory
23               cpan .
24
25               # without arguments, starts CPAN.pm shell
26               cpan
27
28               # without arguments, but some switches
29               cpan [-ahpruvACDLOPX]
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 module [ module ... ]
85           Install the specified modules. With no other switches, this switch
86           is implied.
87
88       -I  Load "local::lib" (think like "-I" for loading lib paths). Too bad
89           "-l" was already taken.
90
91       -j Config.pm
92           Load the file that has the CPAN configuration data. This should
93           have the same format as the standard CPAN/Config.pm file, which
94           defines $CPAN::Config as an anonymous hash.
95
96       -J  Dump the configuration in the same format that CPAN.pm uses. This
97           is useful for checking the configuration as well as using the dump
98           as a starting point for a new, custom configuration.
99
100       -l  List all installed modules with their versions
101
102       -L author [ author ... ]
103           List the modules by the specified authors.
104
105       -m  Make the specified modules.
106
107       -M mirror1,mirror2,...
108           A comma-separated list of mirrors to use for just this run. The
109           "-P" option can find them for you automatically.
110
111       -n  Do a dry run, but don't actually install anything. (unimplemented)
112
113       -O  Show the out-of-date modules.
114
115       -p  Ping the configured mirrors and print a report
116
117       -P  Find the best mirrors you could be using and use them for the
118           current session.
119
120       -r  Recompiles dynamically loaded modules with CPAN::Shell->recompile.
121
122       -s  Drop in the CPAN.pm shell. This command does this automatically if
123           you don't specify any arguments.
124
125       -t module [ module ... ]
126           Run a `make test` on the specified modules.
127
128       -T  Do not test modules. Simply install them.
129
130       -u  Upgrade all installed modules. Blindly doing this can really break
131           things, so keep a backup.
132
133       -v  Print the script version and CPAN.pm version then exit.
134
135       -V  Print detailed information about the cpan client.
136
137       -w  UNIMPLEMENTED
138
139           Turn on cpan warnings. This checks various things, like directory
140           permissions, and tells you about problems you might have.
141
142       -x module [ module ... ]
143           Find close matches to the named modules that you think you might
144           have mistyped. This requires the optional installation of
145           Text::Levenshtein or Text::Levenshtein::Damerau.
146
147       -X  Dump all the namespaces to standard output.
148
149   Examples
150               # print a help message
151               cpan -h
152
153               # print the version numbers
154               cpan -v
155
156               # create an autobundle
157               cpan -a
158
159               # recompile modules
160               cpan -r
161
162               # upgrade all installed modules
163               cpan -u
164
165               # install modules ( sole -i is optional )
166               cpan -i Netscape::Booksmarks Business::ISBN
167
168               # force install modules ( must use -i )
169               cpan -fi CGI::Minimal URI
170
171               # install modules but without testing them
172               cpan -Ti CGI::Minimal URI
173
174   Environment variables
175       There are several components in CPAN.pm that use environment variables.
176       The build tools, ExtUtils::MakeMaker and Module::Build use some, while
177       others matter to the levels above them. Some of these are specified by
178       the Perl Toolchain Gang:
179
180       Lancaster Consensus:
181       <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>
182
183       Oslo Consensus:
184       <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/oslo-consensus.md>
185
186       NONINTERACTIVE_TESTING
187           Assume no one is paying attention and skips prompts for
188           distributions that do that correctly. cpan(1) sets this to 1 unless
189           it already has a value (even if that value is false).
190
191       PERL_MM_USE_DEFAULT
192           Use the default answer for a prompted questions. cpan(1) sets this
193           to 1 unless it already has a value (even if that value is false).
194
195       CPAN_OPTS
196           As with "PERL5OPT", a string of additional cpan(1) options to add
197           to those you specify on the command line.
198
199       CPANSCRIPT_LOGLEVEL
200           The log level to use, with either the embedded, minimal logger or
201           Log::Log4perl if it is installed. Possible values are the same as
202           the "Log::Log4perl" levels: "TRACE", "DEBUG", "INFO", "WARN",
203           "ERROR", and "FATAL". The default is "INFO".
204
205       GIT_COMMAND
206           The path to the "git" binary to use for the Git features. The
207           default is "/usr/local/bin/git".
208

EXIT VALUES

210       The script exits with zero if it thinks that everything worked, or a
211       positive number if it thinks that something failed. Note, however, that
212       in some cases it has to divine a failure by the output of things it
213       does not control. For now, the exit codes are vague:
214
215               1       An unknown error
216
217               2       The was an external problem
218
219               4       There was an internal problem with the script
220
221               8       A module failed to install
222

TO DO

224       * one shot configuration values from the command line
225

BUGS

227       * none noted
228

SOURCE AVAILABILITY

234       This code is in Github in the CPAN.pm repository:
235
236               https://github.com/andk/cpanpm
237
238       The source used to be tracked separately in another GitHub repo, but
239       the canonical source is now in the above repo.
240

CREDITS

242       Japheth Cleaver added the bits to allow a forced install (-f).
243
244       Jim Brandt suggest and provided the initial implementation for the up-
245       to-date and Changes features.
246
247       Adam Kennedy pointed out that exit() causes problems on Windows where
248       this script ends up with a .bat extension
249

AUTHOR

251       brian d foy, "<bdfoy@cpan.org>"
252

COPYRIGHT

254       Copyright (c) 2001-2015, brian d foy, All Rights Reserved.
255
256       You may redistribute this under the same terms as Perl itself.
257
258
259
260perl v5.38.0                      2023-07-20                           CPAN(1)