App::Cpan(3pm)

1App::Cpan(3)          User Contributed Perl Documentation         App::Cpan(3)
2
3
4

NAME

6       App::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 Concensus:
181       <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>
182
183       Oslo Concensus:
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 "PERL5OPTS", 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
209   Methods
210       run()
211           Just do it.
212
213           The "run" method returns 0 on success and a positive number on
214           failure. See the section on EXIT CODES for details on the values.
215
216           CPAN.pm sends all the good stuff either to STDOUT, or to a temp
217           file if $CPAN::Be_Silent is set. I have to intercept that output so
218           I can find out what happened.
219
220           Stolen from File::Path::Expand
221

EXIT VALUES

223       The script exits with zero if it thinks that everything worked, or a
224       positive number if it thinks that something failed. Note, however, that
225       in some cases it has to divine a failure by the output of things it
226       does not control. For now, the exit codes are vague:
227
228               1       An unknown error
229
230               2       The was an external problem
231
232               4       There was an internal problem with the script
233
234               8       A module failed to install
235

TO DO

237       * There is initial support for Log4perl if it is available, but I
238       haven't gone through everything to make the NullLogger work out
239       correctly if Log4perl is not installed.
240
241       * When I capture CPAN.pm output, I need to check for errors and report
242       them to the user.
243
244       * Warnings switch
245
246       * Check then exit
247

BUGS

249       * none noted
250

SOURCE AVAILABILITY

255       This code is in Github in the CPAN.pm repository:
256
257               https://github.com/andk/cpanpm
258
259       The source used to be tracked separately in another GitHub repo, but
260       the canonical source is now in the above repo.
261

CREDITS

263       Japheth Cleaver added the bits to allow a forced install ("-f").
264
265       Jim Brandt suggest and provided the initial implementation for the up-
266       to-date and Changes features.
267
268       Adam Kennedy pointed out that "exit()" causes problems on Windows where
269       this script ends up with a .bat extension
270
271       David Golden helps integrate this into the "CPAN.pm" repos.
272

AUTHOR

274       brian d foy, "<bdfoy@cpan.org>"
275

COPYRIGHT

277       Copyright (c) 2001-2015, brian d foy, All Rights Reserved.
278
279       You may redistribute this under the same terms as Perl itself.
280
281
282
283perl v5.26.3                      2019-05-14                      App::Cpan(3)