1App::cpanminus(3) User Contributed Perl Documentation App::cpanminus(3)
2
6 App::cpanminus - get, unpack, build and install modules from CPAN
7
9 cpanm Module
10 cpanm MIYAGAWA/Plack-1.0000.tar.gz
11 cpanm ~/mydists/MyCompany-Framework-1.0.tar.gz
12 cpanm http://example.com/MyModule-0.1.tar.gz
13 cpanm http://github.com/miyagawa/Tatsumaki/tarball/master
14 cpanm --interactive Task::Kensho
15 Run "cpanm -h" for more options.
17
19 cpanminus is a script to get, unpack, build and install modules from
20 CPAN.
21 Why? It's dependency free, requires zero configuration, and stands
23 alone -- but it's maintainable and extensible with plugins and friendly
24 to shell scripting. When running, it requires only 10MB of RAM.
25
27 There are Debian packages, RPMs, FreeBSD ports, and packages for other
28 operation systems available. If you want to use the package management
29 system, search for cpanminus and use the appropriate command to
30 install. This makes it easy to install "cpanm" to your system without
31 thinking about where to install, and later upgrade.
32 If you want to build the latest from source,
34 git clone git://github.com/miyagawa/cpanminus.git
36 cd cpanminus
37 perl Makefile.PL
38 make install # or sudo make install if you're non root
39 This will install "cpanm" to your bin directory like "/usr/local/bin"
41 (unless you configured "INSTALL_BASE" with local::lib), so you might
42 need to sudo. Later you can say "cpanm --self-upgrade --sudo" to
43 upgrade to the latest version.
44 Otherwise,
46 cd ~/bin
48 wget http://xrl.us/cpanm
49 chmod +x cpanm
50 # edit shebang if you don't have /usr/bin/env
51 just works, but be sure to grab the new version manually when you
53 upgrade ("--self-upgrade" might not work).
54
56 perl 5.8 or later (Actually I believe it works with pre 5.8 too but I
57 haven't tested this).
58 · 'tar' executable (bsdtar or GNU tar version 1.22 are rcommended) or
60 Archive::Tar to unpack files.
61 · C compiler, if you want to build XS modules.
63 And optionally:
65 · make, if you want to reliably install MakeMaker based modules
67 · Module::Build (core in 5.10) to install Build.PL based modules
69
71 WARNING: plugin API is not stable so this feature is turned off by
72 default for now. To enable plugins you have to be savvy enough to look
73 at the build.log or read the source code to see how :)
74 The cpanminus core is a compact and simple 1000 lines of code (with
76 some embedded utilities and documents) but can be extended by writing
77 plugins. Plugins are flat perl scripts placed inside
78 "~/.cpanm/plugins". You can copy (or symlink, if you're a developer) a
79 plugin file to the directory to enable plugins. Delete the file or
80 symlink to disable it.
81 See the "plugins/" directory in the git repository
83 <http://github.com/miyagawa/cpanminus> for the list of available and
84 sample plugins.
85
87 Another CPAN installer?
88 OK, the first motivation was this: the CPAN shell runs out of memory
89 (or swaps heavily and gets really slow) on Slicehost/linode's most
90 affordable plan with only 256MB RAM. Should I pay more to install perl
91 modules from CPAN? I don't think so.
92 But why a new client?
94 First of all, I have no intention to dis CPAN or CPANPLUS developers.
95 Don't get me wrong. They're great tools I've used for literally years
96 (you know how many modules I have on CPAN, right?). I really respect
97 their efforts of maintaining the most important tools in the CPAN
98 toolchain ecosystem.
99 However, for less experienced users (mostly from outside the Perl
101 community), or even really experienced Perl developers who know how to
102 shoot themselves in their feet, setting up the CPAN toolchain often
103 feels like yak shaving, especially when all they want to do is just
104 install some modules and start writing code.
105 In particular, here are the few issues I've observed:
107 · They ask too many questions and do not provide enough sane
109 defaults. A normal user doesn't (and shouldn't have to) know what's
110 the right answer for the question "Parameters for the 'perl
111 Build.PL' command? []"
112 · They provide very noisy output by default.
114 · They fetch and rebuild their indexes almost every day, and this
116 takes time.
117 · ... and they hog 200MB of memory and thrashes/OOMs on my 256MB VPS
119 cpanminus is designed to be very quiet (but logs all output to
121 "~/.cpanm/build.log") and to pick the sanest possible defaults without
122 asking any questions -- to just work.
123 Note that most of these problems with existing tools are rare, or are
125 just overstated. They might already be fixed, or can be configured to
126 work nicer. For instance, the latest CPAN.pm dev release has a much
127 better first time configuration experience than ever before.
128 I know there's a reason for them to have many options and questions,
130 because they're meant to work everywhere for everybody.
131 Of course I should have contributed back to CPAN/CPANPLUS instead of
133 writing a new client, but CPAN.pm is nearly impossible (for anyone
134 other than andk or xdg) to maintain (that's why CPANPLUS was born,
135 right?) and CPANPLUS is a huge beast for me to start working on.
136 Are you on drugs?
138 Yeah, I think my brain has been damaged since I looked at PyPI,
139 gemcutter, pip and rip. They're quite nice and I really wanted
140 something as nice for CPAN which I love.
141 How does this thing work?
143 Imagine you don't have CPAN or CPANPLUS. You search for a module on the
144 CPAN search site, download a tarball, unpack it and then run "perl
145 Makefile.PL" (or "perl Build.PL"). If the module has dependencies you
146 probably have to resolve those dependencies by hand before doing so.
147 Then you run the unit tests and "make install" (or "./Build install").
148 cpanminus automates that.
150 Zero-conf? How does this module get/parse/update the CPAN index?
152 It queries the CPAN Meta DB site running on Google AppEngine at
153 <http://cpanmetadb.appspot.com/>. The site is updated every hour to
154 reflect the latest changes from fast syncing mirrors. The script then
155 also falls back to the site <http://search.cpan.org/>. I've been
156 talking to and working with with the QA/toolchain people for building a
157 more reliable CPAN DB website.
158 Fetched files are unpacked in "~/.cpanm". You can configure this with
160 the "PERL_CPANM_HOME" environment variable.
161 Where does this install modules to? Do I need root access?
163 It installs to wherever ExtUtils::MakeMaker and Module::Build are
164 configured to (via "PERL_MM_OPT" and "MODULEBUILDRC"). So if you're
165 using local::lib, then it installs to your local perl5 directory.
166 Otherwise it installs to the siteperl directory.
167 cpanminus at a boot time checks whether you have configured local::lib,
169 or have the permission to install modules to the sitelib directory. If
170 neither, it automatically sets up local::lib compatible installation
171 path in a "perl5" directory under your home directory. To avoid this,
172 run the script as the root user or with "--sudo" option.
173 This local::lib automatic integration is still considered alpha and in
175 the work -- more bootstrapping is under development. Stay tuned.
176 Does this really work?
178 I tested installing MojoMojo, Task::Kensho, KiokuDB, Catalyst, Jifty
179 and Plack using cpanminus and the installations including dependencies
180 were mostly successful. More than half of CPAN behaves really nicely
181 and appears to work.
182 However, there might be some distributions that will miserably fail,
184 because of nasty edge cases. Here are some examples:
185 · Packages uploaded to PAUSE in 90s which don't live under the
187 standard "authors/id/A/AA" directory hierarchy.
188 · Distributions with a "Makefile.PL" or "Build.PL" that asks you
190 questions without using "prompt" function. However cpanminus has a
191 mechanism to kill those questions with a timeout, and you can
192 always say "--interactive" to make the configuration interactive.
193 · Distributions that do not shipped with "META.yml" file but do
195 require some specific version of toolchain for configuration.
196 · Distributions that test a SIGNATURE in the "*.t" unit tests and has
198 "MANIFEST.SKIP" file in the distribution at the same time. The
199 intent of signature testing is to provide some degree of security,
200 but running it in unit tests is too late as it occurs after running
201 "Makefile.PL". cpanminus has a "verify_signature" plugin to verify
202 the dist before configurations.
203 · Distributions that have a "META.yml" file that is encoded in YAML
205 1.1 format using YAML::XS. This will be eventually solved once we
206 move to "META.json".
207 cpanminus intends to work for 99.9% of modules on CPAN for 99.9% of
209 people. It may not be perfect, but it should just work in most cases.
210 If this tool doesn't work for your very rare environment, then I'm
212 sorry, but you should use CPAN or CPANPLUS, or build and install
213 modules manually.
214 That sounds fantastic. Should I switch to this from CPAN(PLUS)?
216 If you have CPAN or CPANPLUS working then you may want to keep using
217 CPAN or CPANPLUS in the longer term, but I hope this can be a quite
218 handy alternative to them for people in other situations. And
219 apparently, many people love (at least the idea of) this software :)
220
222 Copyright 2010- Tatsuhiko Miyagawa
223 The standalone executable contains the following modules embedded.
225 Parse::CPAN::Meta Copyright 2006-2009 Adam Kennedy
227 local::lib Copyright 2007-2009 Matt S Trout
228 HTTP::Lite Copyright 2000-2002 Roy Hopper, 2009 Adam Kennedy
229 Module::Metadata Copyright 2001-2006 Ken Williams. 2010 Matt S Trout
230
232 Same as Perl.
233
235 CONTRIBUTORS
236 Patches and code improvements were contributed by:
237 Goro Fuji, Kazuhiro Osawa, Tokuhiro Matsuno, Kenichi Ishigaki, Ian
239 Wells, Pedro Melo, Masayoshi Sekimura, Matt S Trout, squeeky, horus and
240 Ingy dot Net.
241 ACKNOWLEDGEMENTS
243 Bug reports, suggestions and feedbacks were sent by, or general
244 acknowledgement goes to:
245 Jesse Vincent, David Golden, Andreas Koenig, Jos Boumans, Chris
247 Williams, Adam Kennedy, Audrey Tang, J. Shirley, Chris Prather, Jesse
248 Luehrs, Marcus Ramberg, Shawn M Moore, chocolateboy, Chirs Nehren,
249 Jonathan Rockway, Leon Brocard, Simon Elliott, Ricardo Signes, AEvar
250 Arnfjord Bjarmason, Eric Wilhelm, Florian Ragwitz and xaicron.
251
253 <http://github.com/miyagawa/cpanminus> - source code repository, issue
254 tracker
255 <irc://irc.perl.org/#toolchain> - discussions about Perl toolchain. I'm
256 there.
257
259 This software is provided "as-is," without any express or implied
260 warranty. In no event shall the author be held liable for any damages
261 arising from the use of the software.
262
264 CPAN CPANPLUS pip
265perl v5.12.0 2010-04-14 App::cpanminus(3)