diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/cpan.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/cpan.1 | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/cpan.1 b/upstream/mageia-cauldron/man1/cpan.1 new file mode 100644 index 00000000..45dbf68b --- /dev/null +++ b/upstream/mageia-cauldron/man1/cpan.1 @@ -0,0 +1,340 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CPAN 1" +.TH CPAN 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +cpan \- easily interact with CPAN from the command line +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& # with arguments and no switches, installs specified modules +\& cpan module_name [ module_name ... ] +\& +\& # with switches, installs modules with extra behavior +\& cpan [\-cfFimtTw] module_name [ module_name ... ] +\& +\& # use local::lib +\& cpan \-I module_name [ module_name ... ] +\& +\& # one time mirror override for faster mirrors +\& cpan \-p ... +\& +\& # with just the dot, install from the distribution in the +\& # current directory +\& cpan . +\& +\& # without arguments, starts CPAN.pm shell +\& cpan +\& +\& # without arguments, but some switches +\& cpan [\-ahpruvACDLOPX] +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This script provides a command interface (not a shell) to CPAN. At the +moment it uses CPAN.pm to do the work, but it is not a one-shot command +runner for CPAN.pm. +.SS Options +.IX Subsection "Options" +.IP \-a 4 +.IX Item "-a" +Creates a CPAN.pm autobundle with CPAN::Shell\->autobundle. +.IP "\-A module [ module ... ]" 4 +.IX Item "-A module [ module ... ]" +Shows the primary maintainers for the specified modules. +.IP "\-c module" 4 +.IX Item "-c module" +Runs a `make clean` in the specified module's directories. +.IP "\-C module [ module ... ]" 4 +.IX Item "-C module [ module ... ]" +Show the \fIChanges\fR files for the specified modules +.IP "\-D module [ module ... ]" 4 +.IX Item "-D module [ module ... ]" +Show the module details. This prints one line for each out-of-date module +(meaning, modules locally installed but have newer versions on CPAN). +Each line has three columns: module name, local version, and CPAN +version. +.IP \-f 4 +.IX Item "-f" +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: +.Sp +.Vb 1 +\& % cpan \-f \-i Module::Foo +.Ve +.IP \-F 4 +.IX Item "-F" +Turn off CPAN.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'\fR, and that config sets up its own work directories. +.IP "\-g module [ module ... ]" 4 +.IX Item "-g module [ module ... ]" +Downloads to the current directory the latest distribution of the module. +.IP "\-G module [ module ... ]" 4 +.IX Item "-G module [ module ... ]" +UNIMPLEMENTED +.Sp +Download to the current directory the latest distribution of the +modules, unpack each distribution, and create a git repository for each +distribution. +.Sp +If you want this feature, check out Yanick Champoux's \f(CW\*(C`Git::CPAN::Patch\*(C'\fR +distribution. +.IP \-h 4 +.IX Item "-h" +Print a help message and exit. When you specify \f(CW\*(C`\-h\*(C'\fR, it ignores all +of the other options and arguments. +.IP "\-i module [ module ... ]" 4 +.IX Item "-i module [ module ... ]" +Install the specified modules. With no other switches, this switch +is implied. +.IP \-I 4 +.IX Item "-I" +Load \f(CW\*(C`local::lib\*(C'\fR (think like \f(CW\*(C`\-I\*(C'\fR for loading lib paths). Too bad +\&\f(CW\*(C`\-l\*(C'\fR was already taken. +.IP "\-j Config.pm" 4 +.IX Item "-j Config.pm" +Load the file that has the CPAN configuration data. This should have the +same format as the standard \fICPAN/Config.pm\fR file, which defines +\&\f(CW$CPAN::Config\fR as an anonymous hash. +.IP \-J 4 +.IX Item "-J" +Dump the configuration in the same format that CPAN.pm uses. This is useful +for checking the configuration as well as using the dump as a starting point +for a new, custom configuration. +.IP \-l 4 +.IX Item "-l" +List all installed modules with their versions +.IP "\-L author [ author ... ]" 4 +.IX Item "-L author [ author ... ]" +List the modules by the specified authors. +.IP \-m 4 +.IX Item "-m" +Make the specified modules. +.IP "\-M mirror1,mirror2,..." 4 +.IX Item "-M mirror1,mirror2,..." +A comma-separated list of mirrors to use for just this run. The \f(CW\*(C`\-P\*(C'\fR +option can find them for you automatically. +.IP \-n 4 +.IX Item "-n" +Do a dry run, but don't actually install anything. (unimplemented) +.IP \-O 4 +.IX Item "-O" +Show the out-of-date modules. +.IP \-p 4 +.IX Item "-p" +Ping the configured mirrors and print a report +.IP \-P 4 +.IX Item "-P" +Find the best mirrors you could be using and use them for the current +session. +.IP \-r 4 +.IX Item "-r" +Recompiles dynamically loaded modules with CPAN::Shell\->recompile. +.IP \-s 4 +.IX Item "-s" +Drop in the CPAN.pm shell. This command does this automatically if you don't +specify any arguments. +.IP "\-t module [ module ... ]" 4 +.IX Item "-t module [ module ... ]" +Run a `make test` on the specified modules. +.IP \-T 4 +.IX Item "-T" +Do not test modules. Simply install them. +.IP \-u 4 +.IX Item "-u" +Upgrade all installed modules. Blindly doing this can really break things, +so keep a backup. +.IP \-v 4 +.IX Item "-v" +Print the script version and CPAN.pm version then exit. +.IP \-V 4 +.IX Item "-V" +Print detailed information about the cpan client. +.IP \-w 4 +.IX Item "-w" +UNIMPLEMENTED +.Sp +Turn on cpan warnings. This checks various things, like directory permissions, +and tells you about problems you might have. +.IP "\-x module [ module ... ]" 4 +.IX Item "-x module [ module ... ]" +Find close matches to the named modules that you think you might have +mistyped. This requires the optional installation of Text::Levenshtein or +Text::Levenshtein::Damerau. +.IP \-X 4 +.IX Item "-X" +Dump all the namespaces to standard output. +.SS Examples +.IX Subsection "Examples" +.Vb 2 +\& # 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 +\& +\& # install modules but without testing them +\& cpan \-Ti CGI::Minimal URI +.Ve +.SS "Environment variables" +.IX Subsection "Environment variables" +There are several components in CPAN.pm that use environment variables. +The build tools, ExtUtils::MakeMaker and Module::Build use some, +while others matter to the levels above them. Some of these are specified +by the Perl Toolchain Gang: +.PP +Lancaster Consensus: <https://github.com/Perl\-Toolchain\-Gang/toolchain\-site/blob/master/lancaster\-consensus.md> +.PP +Oslo Consensus: <https://github.com/Perl\-Toolchain\-Gang/toolchain\-site/blob/master/oslo\-consensus.md> +.IP NONINTERACTIVE_TESTING 4 +.IX Item "NONINTERACTIVE_TESTING" +Assume no one is paying attention and skips prompts for distributions +that do that correctly. \f(CWcpan(1)\fR sets this to \f(CW1\fR unless it already +has a value (even if that value is false). +.IP PERL_MM_USE_DEFAULT 4 +.IX Item "PERL_MM_USE_DEFAULT" +Use the default answer for a prompted questions. \f(CWcpan(1)\fR sets this +to \f(CW1\fR unless it already has a value (even if that value is false). +.IP CPAN_OPTS 4 +.IX Item "CPAN_OPTS" +As with \f(CW\*(C`PERL5OPT\*(C'\fR, a string of additional \f(CWcpan(1)\fR options to +add to those you specify on the command line. +.IP CPANSCRIPT_LOGLEVEL 4 +.IX Item "CPANSCRIPT_LOGLEVEL" +The log level to use, with either the embedded, minimal logger or +Log::Log4perl if it is installed. Possible values are the same as +the \f(CW\*(C`Log::Log4perl\*(C'\fR levels: \f(CW\*(C`TRACE\*(C'\fR, \f(CW\*(C`DEBUG\*(C'\fR, \f(CW\*(C`INFO\*(C'\fR, \f(CW\*(C`WARN\*(C'\fR, +\&\f(CW\*(C`ERROR\*(C'\fR, and \f(CW\*(C`FATAL\*(C'\fR. The default is \f(CW\*(C`INFO\*(C'\fR. +.IP GIT_COMMAND 4 +.IX Item "GIT_COMMAND" +The path to the \f(CW\*(C`git\*(C'\fR binary to use for the Git features. The default +is \f(CW\*(C`/usr/local/bin/git\*(C'\fR. +.SH "EXIT VALUES" +.IX Header "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: +.PP +.Vb 1 +\& 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 +.Ve +.SH "TO DO" +.IX Header "TO DO" +* one shot configuration values from the command line +.SH BUGS +.IX Header "BUGS" +* none noted +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Most behaviour, including environment variables and configuration, +comes directly from CPAN.pm. +.SH "SOURCE AVAILABILITY" +.IX Header "SOURCE AVAILABILITY" +This code is in Github in the CPAN.pm repository: +.PP +.Vb 1 +\& https://github.com/andk/cpanpm +.Ve +.PP +The source used to be tracked separately in another GitHub repo, +but the canonical source is now in the above repo. +.SH CREDITS +.IX Header "CREDITS" +Japheth Cleaver added the bits to allow a forced install (\-f). +.PP +Jim Brandt suggest and provided the initial implementation for the +up-to-date and Changes features. +.PP +Adam Kennedy pointed out that \fBexit()\fR causes problems on Windows +where this script ends up with a .bat extension +.SH AUTHOR +.IX Header "AUTHOR" +brian d foy, \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 2001\-2015, brian d foy, All Rights Reserved. +.PP +You may redistribute this under the same terms as Perl itself. |