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           If the file does not exist, "cpan" dies.
97
98       -J  Dump the configuration in the same format that CPAN.pm uses. This
99           is useful for checking the configuration as well as using the dump
100           as a starting point for a new, custom configuration.
101
102       -l  List all installed modules with their versions
103
104       -L author [ author ... ]
105           List the modules by the specified authors.
106
107       -m  Make the specified modules.
108
109       -M mirror1,mirror2,...
110           A comma-separated list of mirrors to use for just this run. The
111           "-P" option can find them for you automatically.
112
113       -n  Do a dry run, but don't actually install anything. (unimplemented)
114
115       -O  Show the out-of-date modules.
116
117       -p  Ping the configured mirrors and print a report
118
119       -P  Find the best mirrors you could be using and use them for the
120           current session.
121
122       -r  Recompiles dynamically loaded modules with CPAN::Shell->recompile.
123
124       -s  Drop in the CPAN.pm shell. This command does this automatically if
125           you don't specify any arguments.
126
127       -t module [ module ... ]
128           Run a `make test` on the specified modules.
129
130       -T  Do not test modules. Simply install them.
131
132       -u  Upgrade all installed modules. Blindly doing this can really break
133           things, so keep a backup.
134
135       -v  Print the script version and CPAN.pm version then exit.
136
137       -V  Print detailed information about the cpan client.
138
139       -w  UNIMPLEMENTED
140
141           Turn on cpan warnings. This checks various things, like directory
142           permissions, and tells you about problems you might have.
143
144       -x module [ module ... ]
145           Find close matches to the named modules that you think you might
146           have mistyped. This requires the optional installation of
147           Text::Levenshtein or Text::Levenshtein::Damerau.
148
149       -X  Dump all the namespaces to standard output.
150
151   Examples
152               # print a help message
153               cpan -h
154
155               # print the version numbers
156               cpan -v
157
158               # create an autobundle
159               cpan -a
160
161               # recompile modules
162               cpan -r
163
164               # upgrade all installed modules
165               cpan -u
166
167               # install modules ( sole -i is optional )
168               cpan -i Netscape::Booksmarks Business::ISBN
169
170               # force install modules ( must use -i )
171               cpan -fi CGI::Minimal URI
172
173               # install modules but without testing them
174               cpan -Ti CGI::Minimal URI
175
176   Environment variables
177       There are several components in CPAN.pm that use environment variables.
178       The build tools, ExtUtils::MakeMaker and Module::Build use some, while
179       others matter to the levels above them. Some of these are specified by
180       the Perl Toolchain Gang:
181
182       Lancaster Consensus:
183       <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>
184
185       Oslo Consensus:
186       <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/oslo-consensus.md>
187
188       NONINTERACTIVE_TESTING
189           Assume no one is paying attention and skips prompts for
190           distributions that do that correctly. cpan(1) sets this to 1 unless
191           it already has a value (even if that value is false).
192
193       PERL_MM_USE_DEFAULT
194           Use the default answer for a prompted questions. cpan(1) sets this
195           to 1 unless it already has a value (even if that value is false).
196
197       CPAN_OPTS
198           As with "PERL5OPT", a string of additional cpan(1) options to add
199           to those you specify on the command line.
200
201       CPANSCRIPT_LOGLEVEL
202           The log level to use, with either the embedded, minimal logger or
203           Log::Log4perl if it is installed. Possible values are the same as
204           the "Log::Log4perl" levels: "TRACE", "DEBUG", "INFO", "WARN",
205           "ERROR", and "FATAL". The default is "INFO".
206
207       GIT_COMMAND
208           The path to the "git" binary to use for the Git features. The
209           default is "/usr/local/bin/git".
210
211   Methods
212       run( ARGS )
213           Just do it.
214
215           The "run" method returns 0 on success and a positive number on
216           failure. See the section on EXIT CODES for details on the values.
217
218           CPAN.pm sends all the good stuff either to STDOUT, or to a temp
219           file if $CPAN::Be_Silent is set. I have to intercept that output so
220           I can find out what happened.
221
222           Stolen from File::Path::Expand
223

EXIT VALUES

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

TO DO

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

BUGS

251       * none noted
252

SOURCE AVAILABILITY

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

CREDITS

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

AUTHOR

278       brian d foy, "<bdfoy@cpan.org>"
279

COPYRIGHT

281       Copyright (c) 2001-2021, brian d foy, All Rights Reserved.
282
283       You may redistribute this under the same terms as Perl itself.
284
285
286
287perl v5.36.1                      2023-05-15                      App::Cpan(3)