| 1 | package App::cpanminus; | ||
| 2 | 1 | our $VERSION = "1.7049"; | |
| 3 | |||
| 4 | =encoding utf8 | ||
| 5 | |||
| 6 | =head1 NAME | ||
| 7 | |||
| 8 | App::cpanminus - get, unpack, build and install modules from CPAN | ||
| 9 | |||
| 10 | =head1 SYNOPSIS | ||
| 11 | |||
| 12 | cpanm Module | ||
| 13 | |||
| 14 | Run C<cpanm -h> or C<perldoc cpanm> for more options. | ||
| 15 | |||
| 16 | =head1 DESCRIPTION | ||
| 17 | |||
| 18 | cpanminus is a script to get, unpack, build and install modules from | ||
| 19 | CPAN and does nothing else. | ||
| 20 | |||
| 21 | It's dependency free (can bootstrap itself), requires zero | ||
| 22 | configuration, and stands alone. When running, it requires only 10MB | ||
| 23 | of RAM. | ||
| 24 | |||
| 25 | =head1 INSTALLATION | ||
| 26 | |||
| 27 | There are several ways to install cpanminus to your system. | ||
| 28 | |||
| 29 | =head2 Package management system | ||
| 30 | |||
| 31 | There are Debian packages, RPMs, FreeBSD ports, and packages for other | ||
| 32 | operation systems available. If you want to use the package management system, | ||
| 33 | search for cpanminus and use the appropriate command to install. This makes it | ||
| 34 | easy to install C<cpanm> to your system without thinking about where to | ||
| 35 | install, and later upgrade. | ||
| 36 | |||
| 37 | =head2 Installing to system perl | ||
| 38 | |||
| 39 | You can also use the latest cpanminus to install cpanminus itself: | ||
| 40 | |||
| 41 | curl -L https://cpanmin.us | perl - --sudo App::cpanminus | ||
| 42 | |||
| 43 | This will install C<cpanm> to your bin directory like | ||
| 44 | C</usr/local/bin> and you'll need the C<--sudo> option to write to | ||
| 45 | the directory, unless you configured C<INSTALL_BASE> with L<local::lib>. | ||
| 46 | |||
| 47 | =head2 Installing to local perl (perlbrew, plenv etc.) | ||
| 48 | |||
| 49 | If you have perl in your home directory, which is the case if you use | ||
| 50 | tools like L<perlbrew> or plenv, you don't need the C<--sudo> option, since | ||
| 51 | you're most likely to have a write permission to the perl's library | ||
| 52 | path. You can just do: | ||
| 53 | |||
| 54 | curl -L https://cpanmin.us | perl - App::cpanminus | ||
| 55 | |||
| 56 | to install the C<cpanm> executable to the perl's bin path, like | ||
| 57 | C<~/perl5/perlbrew/bin/cpanm>. | ||
| 58 | |||
| 59 | =head2 Downloading the standalone executable | ||
| 60 | |||
| 61 | You can also copy the standalone executable to whatever location you'd like. | ||
| 62 | |||
| 63 | cd ~/bin | ||
| 64 | curl -L https://cpanmin.us/ -o cpanm | ||
| 65 | chmod +x cpanm | ||
| 66 | |||
| 67 | This just works, but be sure to grab the new version manually when you | ||
| 68 | upgrade because C<--self-upgrade> might not work with this installation setup. | ||
| 69 | |||
| 70 | =head2 Troubleshoot: HTTPS warnings | ||
| 71 | |||
| 72 | When you run C<curl> commands above, you may encounter SSL handshake | ||
| 73 | errors or certification warnings. This is due to your HTTP client | ||
| 74 | (curl) being old, or SSL certificates installed on your system needs | ||
| 75 | to be updated. | ||
| 76 | |||
| 77 | You're recommended to update the software or system if you can. If | ||
| 78 | that is impossible or difficult, use the C<-k> option with curl. | ||
| 79 | |||
| 80 | =head1 DEPENDENCIES | ||
| 81 | |||
| 82 | perl 5.8.1 or later. | ||
| 83 | |||
| 84 | =over 4 | ||
| 85 | |||
| 86 | =item * | ||
| 87 | |||
| 88 | 'tar' executable (bsdtar or GNU tar version 1.22 are recommended) or Archive::Tar to unpack files. | ||
| 89 | |||
| 90 | =item * | ||
| 91 | |||
| 92 | C compiler, if you want to build XS modules. | ||
| 93 | |||
| 94 | =item * | ||
| 95 | |||
| 96 | make | ||
| 97 | |||
| 98 | =item * | ||
| 99 | |||
| 100 | Module::Build (core in 5.10) | ||
| 101 | |||
| 102 | =back | ||
| 103 | |||
| 104 | =head1 QUESTIONS | ||
| 105 | |||
| 106 | =head2 How does cpanm get/parse/update the CPAN index? | ||
| 107 | |||
| 108 | It queries the CPAN Meta DB site at L<http://cpanmetadb.plackperl.org/>. | ||
| 109 | The site is updated at least every hour to reflect the latest changes | ||
| 110 | from fast syncing mirrors. The script then also falls back to query the | ||
| 111 | module at L<http://metacpan.org/> using its search API. | ||
| 112 | |||
| 113 | Upon calling these API hosts, cpanm (1.6004 or later) will send the | ||
| 114 | local perl versions to the server in User-Agent string by default. You | ||
| 115 | can turn it off with C<--no-report-perl-version> option. Read more | ||
| 116 | about the option with L<cpanm>, and read more about the privacy policy | ||
| 117 | about this data collection at L<http://cpanmetadb.plackperl.org/#privacy> | ||
| 118 | |||
| 119 | Fetched files are unpacked in C<~/.cpanm> and automatically cleaned up | ||
| 120 | periodically. You can configure the location of this with the | ||
| 121 | C<PERL_CPANM_HOME> environment variable. | ||
| 122 | |||
| 123 | =head2 Where does this install modules to? Do I need root access? | ||
| 124 | |||
| 125 | It installs to wherever ExtUtils::MakeMaker and Module::Build are | ||
| 126 | configured to (via C<PERL_MM_OPT> and C<PERL_MB_OPT>). | ||
| 127 | |||
| 128 | By default, it installs to the site_perl directory that belongs to | ||
| 129 | your perl. You can see the locations for that by running C<perl -V> | ||
| 130 | and it will be likely something under C</opt/local/perl/...> if you're | ||
| 131 | using system perl, or under your home directory if you have built perl | ||
| 132 | yourself using perlbrew or plenv. | ||
| 133 | |||
| 134 | If you've already configured local::lib on your shell, cpanm respects | ||
| 135 | that settings and modules will be installed to your local perl5 | ||
| 136 | directory. | ||
| 137 | |||
| 138 | At a boot time, cpanminus checks whether you have already configured | ||
| 139 | local::lib, or have a permission to install modules to the site_perl | ||
| 140 | directory. If neither, i.e. you're using system perl and do not run | ||
| 141 | cpanm as a root, it automatically sets up local::lib compatible | ||
| 142 | installation path in a C<perl5> directory under your home | ||
| 143 | directory. | ||
| 144 | |||
| 145 | To avoid this, run C<cpanm> either as a root user, with C<--sudo> | ||
| 146 | option, or with C<--local-lib> option. | ||
| 147 | |||
| 148 | =head2 cpanminus can't install the module XYZ. Is it a bug? | ||
| 149 | |||
| 150 | It is more likely a problem with the distribution itself. cpanminus | ||
| 151 | doesn't support or may have issues with distributions such as follows: | ||
| 152 | |||
| 153 | =over 4 | ||
| 154 | |||
| 155 | =item * | ||
| 156 | |||
| 157 | Tests that require input from STDIN. | ||
| 158 | |||
| 159 | =item * | ||
| 160 | |||
| 161 | Build.PL or Makefile.PL that prompts for input even when | ||
| 162 | C<PERL_MM_USE_DEFAULT> is enabled. | ||
| 163 | |||
| 164 | =item * | ||
| 165 | |||
| 166 | Modules that have invalid numeric values as VERSION (such as C<1.1a>) | ||
| 167 | |||
| 168 | =back | ||
| 169 | |||
| 170 | These failures can be reported back to the author of the module so | ||
| 171 | that they can fix it accordingly, rather than to cpanminus. | ||
| 172 | |||
| 173 | =head2 Does cpanm support the feature XYZ of L<CPAN> and L<CPANPLUS>? | ||
| 174 | |||
| 175 | Most likely not. Here are the things that cpanm doesn't do by | ||
| 176 | itself. | ||
| 177 | |||
| 178 | If you need these features, use L<CPAN>, L<CPANPLUS> or the standalone | ||
| 179 | tools that are mentioned. | ||
| 180 | |||
| 181 | =over 4 | ||
| 182 | |||
| 183 | =item * | ||
| 184 | |||
| 185 | CPAN testers reporting. See L<App::cpanminus::reporter> | ||
| 186 | |||
| 187 | =item * | ||
| 188 | |||
| 189 | Building RPM packages from CPAN modules | ||
| 190 | |||
| 191 | =item * | ||
| 192 | |||
| 193 | Listing the outdated modules that needs upgrading. See L<App::cpanoutdated> | ||
| 194 | |||
| 195 | =item * | ||
| 196 | |||
| 197 | Showing the changes of the modules you're about to upgrade. See L<cpan-listchanges> | ||
| 198 | |||
| 199 | =item * | ||
| 200 | |||
| 201 | Patching CPAN modules with distroprefs. | ||
| 202 | |||
| 203 | =back | ||
| 204 | |||
| 205 | See L<cpanm> or C<cpanm -h> to see what cpanminus I<can> do :) | ||
| 206 | |||
| 207 | =head1 COPYRIGHT | ||
| 208 | |||
| 209 | Copyright 2010- Tatsuhiko Miyagawa | ||
| 210 | |||
| 211 | The standalone executable contains the following modules embedded. | ||
| 212 | |||
| 213 | =over 4 | ||
| 214 | |||
| 215 | =item L<CPAN::DistnameInfo> Copyright 2003 Graham Barr | ||
| 216 | |||
| 217 | =item L<local::lib> Copyright 2007-2009 Matt S Trout | ||
| 218 | |||
| 219 | =item L<HTTP::Tiny> Copyright 2011 Christian Hansen | ||
| 220 | |||
| 221 | =item L<Module::Metadata> Copyright 2001-2006 Ken Williams. 2010 Matt S Trout | ||
| 222 | |||
| 223 | =item L<version> Copyright 2004-2010 John Peacock | ||
| 224 | |||
| 225 | =item L<JSON::PP> Copyright 2007-2011 by Makamaka Hannyaharamitu | ||
| 226 | |||
| 227 | =item L<CPAN::Meta>, L<CPAN::Meta::Requirements> Copyright (c) 2010 by David Golden and Ricardo Signes | ||
| 228 | |||
| 229 | =item L<CPAN::Meta::YAML> Copyright 2010 Adam Kennedy | ||
| 230 | |||
| 231 | =item L<CPAN::Meta::Check> Copyright (c) 2012 by Leon Timmermans | ||
| 232 | |||
| 233 | =item L<File::pushd> Copyright 2012 David Golden | ||
| 234 | |||
| 235 | =item L<parent> Copyright (c) 2007-10 Max Maischein | ||
| 236 | |||
| 237 | =item L<Parse::PMFile> Copyright 1995 - 2013 by Andreas Koenig, Copyright 2013 by Kenichi Ishigaki | ||
| 238 | |||
| 239 | =item L<String::ShellQuote> by Roderick Schertler | ||
| 240 | |||
| 241 | |||
| 242 | =back | ||
| 243 | |||
| 244 | =head1 LICENSE | ||
| 245 | |||
| 246 | This software is licensed under the same terms as Perl. | ||
| 247 | |||
| 248 | =head1 CREDITS | ||
| 249 | |||
| 250 | =head2 CONTRIBUTORS | ||
| 251 | |||
| 252 | Patches and code improvements were contributed by: | ||
| 253 | |||
| 254 | Goro Fuji, Kazuhiro Osawa, Tokuhiro Matsuno, Kenichi Ishigaki, Ian | ||
| 255 | Wells, Pedro Melo, Masayoshi Sekimura, Matt S Trout (mst), squeeky, | ||
| 256 | horus and Ingy dot Net. | ||
| 257 | |||
| 258 | =head2 ACKNOWLEDGEMENTS | ||
| 259 | |||
| 260 | Bug reports, suggestions and feedbacks were sent by, or general | ||
| 261 | acknowledgement goes to: | ||
| 262 | |||
| 263 | Jesse Vincent, David Golden, Andreas Koenig, Jos Boumans, Chris | ||
| 264 | Williams, Adam Kennedy, Audrey Tang, J. Shirley, Chris Prather, Jesse | ||
| 265 | Luehrs, Marcus Ramberg, Shawn M Moore, chocolateboy, Chirs Nehren, | ||
| 266 | Jonathan Rockway, Leon Brocard, Simon Elliott, Ricardo Signes, AEvar | ||
| 267 | Arnfjord Bjarmason, Eric Wilhelm, Florian Ragwitz and xaicron. | ||
| 268 | |||
| 269 | =head1 COMMUNITY | ||
| 270 | |||
| 271 | =over 4 | ||
| 272 | |||
| 273 | =item L<http://github.com/miyagawa/cpanminus> - source code repository, issue tracker | ||
| 274 | |||
| 275 | =item L<irc://irc.perl.org/#cpanm> - discussions about cpanm and its related tools | ||
| 276 | |||
| 277 | =back | ||
| 278 | |||
| 279 | =head1 NO WARRANTY | ||
| 280 | |||
| 281 | This software is provided "as-is," without any express or implied | ||
| 282 | warranty. In no event shall the author be held liable for any damages | ||
| 283 | arising from the use of the software. | ||
| 284 | |||
| 285 | =head1 SEE ALSO | ||
| 286 | |||
| 287 | L<CPAN> L<CPANPLUS> L<pip> | ||
| 288 | |||
| 289 | =cut | ||
| 290 | |||
| 291 | 1 | 1; |