App::Cpan(3pm)

1App::Cpan(3pm)         Perl Programmers Reference Guide         App::Cpan(3pm)
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 [-cfFimt] module_name [ module_name ... ]
14
15               # use local::lib
16               cpan -l module_name [ module_name ... ]
17
18               # with just the dot, install from the distribution in the
19               # current directory
20               cpan .
21
22               # without arguments, starts CPAN.pm shell
23               cpan
24
25               # without arguments, but some switches
26               cpan [-ahruvACDLO]
27

DESCRIPTION

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

EXIT VALUES

143       The script exits with zero if it thinks that everything worked, or a
144       positive number if it thinks that something failed. Note, however, that
145       in some cases it has to divine a failure by the output of things it
146       does not control. For now, the exit codes are vague:
147
148               1       An unknown error
149
150               2       The was an external problem
151
152               4       There was an internal problem with the script
153
154               8       A module failed to install
155

TO DO

157       * There is initial support for Log4perl if it is available, but I
158       haven't gone through everything to make the NullLogger work out
159       correctly if Log4perl is not installed.
160
161       * When I capture CPAN.pm output, I need to check for errors and report
162       them to the user.
163

BUGS

165       * none noted
166

SOURCE AVAILABILITY

172       This code is in Github:
173
174               git://github.com/briandfoy/cpan_script.git
175

CREDITS

177       Japheth Cleaver added the bits to allow a forced install (-f).
178
179       Jim Brandt suggest and provided the initial implementation for the up-
180       to-date and Changes features.
181
182       Adam Kennedy pointed out that exit() causes problems on Windows where
183       this script ends up with a .bat extension
184

AUTHOR

186       brian d foy, "<bdfoy@cpan.org>"
187

COPYRIGHT

189       Copyright (c) 2001-2009, brian d foy, All Rights Reserved.
190
191       You may redistribute this under the same terms as Perl itself.
192
193
194
195perl v5.12.4                      2011-06-01                    App::Cpan(3pm)