Source

perl-begin / src / topics / cpan / life-with-cpan / index.html

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
<?xml version="1.0" encoding='utf-8' ?>
<!doctype
    html public "-//w3c//dtd xhtml 1.1//en"
    "http://www.w3.org/tr/xhtml11/dtd/xhtml11.dtd">
<html xml:lang="en-US"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
        <title>Life with CPAN</title><link rel="stylesheet"
        type="text/css" href="default.css" /><meta
        name="MSSmartTagsPreventParsing" content="TRUE" /></head><body>
        <div class="header"><div
                class="navlinks"><a
                    href="http://web.archive.org/web/20080822232114/http://sial.org/howto/perl/">Parent
                    Page</a></div><h1 id="s">Life with
                    CPAN</h1></div><div class="subsection"><a
                href="#s2"><tt
                    class="cmd">perl</tt> Upgrade Bug</a> | <a
                href="#s3">Active
                FTP versus Firewalls</a> | <a
                href="#s4">Preferences
                Questions</a> | <a
                href="#s5">Reconfiguring
                CPAN</a> | <a
                href="#s6">Usage
                Tips</a> | <a
                href="#s7">Debugging
                Module Build Problems</a> | <a
                href="#s8">Using
                CPAN with a non-root account</a></div><div class="bodymain"><p
            class="info">The <a
                href="http://www.cpan.org/">Comprehensive
                Perl Archive Network (CPAN)</a> hosts <a
                href="http://www.perl.org/">Perl</a>
            modules and scripts. The <a
                href="http://search.cpan.org/perldoc/CPAN"
                title="Documentation on the CPAN Perl module"><tt
                    class="perl-module">CPAN</tt></a> module provides an
            interface to query and install modules hosted on <acronym
                title="Comprehensive Perl Archive Network">CPAN</acronym>.
            These pages document the setup and usage of <a
                href="http://search.cpan.org/perldoc/CPAN"
                title="Documentation on the CPAN Perl module"><tt
                    class="perl-module">CPAN</tt></a>, with attention to common
            tasks and pitfalls along the way.</p><p class="info">Perl
 modules used in production must be saved locally, either under version
 control, a package system, or software depot. Doing so ensures the modules can
 be installed on new systems, or rebuilt on new platforms.  This supports
 reproducible module installs over time, as <acronym title="Comprehensive Perl
     Archive Network">CPAN</acronym> modules may change or be removed without
 warning.</p><p class="info">Use <a
     href="http://search.cpan.org/perldoc/CPAN::Reporter"
     title="Documentation on the CPAN::Reporter Perl module"><tt
         class="perl-module">CPAN::Reporter</tt></a> to <a
     href="http://use.perl.org/article.pl?sid=06/11/08/1256207">submit
     module test results</a>. Try <a
     href="http://use.perl.org/%7EShlomi+Fish/journal/32367">SmokeAuto
     for automated module testing</a>.</p><h3 id="s1.1">
         Alternatives</h3><p class="info">Other means of
 installing <tt class="cmd">perl</tt> modules from <acronym
     title="Comprehensive Perl Archive Network">CPAN</acronym> include the
 following, which are not discussed in detail here.</p><ul class="list"><li><a
         href="http://search.cpan.org/perldoc/CPANPLUS"
         title="Documentation on the CPANPLUS Perl module"><tt
             class="perl-module">CPANPLUS</tt></a>. “<tt
         class="code">CPAN++</tt> (also referred to and pronounced as <tt
         class="code">CPANPLUS</tt>) is a new and flexible method of <tt
         class="cmd">perl</tt> module management and installation using the
     <acronym title="Comprehensive Perl Archive Network">CPAN</acronym>. It
     aims to be a rewrite, and in time a replacement to the current <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> module. In  addition to fixing
     some long-standing problems, <tt class="code">CPAN++</tt> includes new
     features, such as module uninstall.”<br />&nbsp;</li><li>PAR - <a
         href="http://par.perl.org/">Cross-Platform
         Packaging and Deployment tool</a>.<br />&nbsp;</li><li><a
         href="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/">Perl
         Package Manager (PPM)</a> - Included with <a
         href="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/">ActiveState
         Perl</a>.<br />&nbsp;</li><li><p>Other. Some vendors make <tt
         class="cmd">perl</tt> modules available via other methods, such as
     ActiveState’s <a
         href="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/"><acronym
             title="Perl Package Manager">PPM</acronym></a>, the <a
         href="http://www.freebsd.org/ports/">FreeBSD
         ports</a> system, or similar package software. On <a
         href="macosx/">Mac
         OS X, install XCode</a>, or use on of the various package systems
     available. These offer tight integration with the system in question, but
     may include outdated modules or use different naming conventions and
     filesystem layouts.</p><p class="note">For example, <tt
         class="code">p5-libwww</tt> is the FreeBSD port
of the module distribution <tt class="code">libwww-perl</tt> on <acronym
    title="Comprehensive Perl Archive Network">CPAN</acronym>, and <a
    href="http://search.cpan.org/perldoc/LWP::UserAgent"
    title="Documentation on the LWP::UserAgent Perl module"><tt
        class="perl-module">LWP::UserAgent</tt></a> a module found in that
distribution. The following commands are equivalent means to install <tt
    class="code">libwww-perl</tt> via the FreeBSD ports system, <tt
    class="cmd">yum</tt> on RedHat systems, or the <tt class="cmd">cpan</tt>
command included with modern versions of <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a>.</p><p class="data-shell">#
<kbd>portinstall p5-libwww</kbd><br /># <kbd>yum -y install
    perl-libwww-perl</kbd><br /># <kbd>cpan -i LWP::UserAgent</kbd></p><p
class="info">To lookup the documentation for a module, use <tt
    class="code">http://search.cpan.org/perldoc/<kbd
        class="input">Module::Name</kbd></tt>. The documentation should also
show the distribution a module belongs to, for example <a
    href="http://search.cpan.org/perldoc/Data::Dumper"
    title="Documentation on the Data::Dumper Perl module"><tt
        class="perl-module">Data::Dumper</tt></a>. Other search interfaces
include the <a
    href="http://search.cpan.org/"><acronym
        title="Comprehensive Perl Archive Network">CPAN</acronym> Search
    Site</a> or the <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> shell search
features.</p></li><li>Conversion scripts. <a
    href="http://perl.arix.com/cpan2rpm/"><tt
        class="cmd">cpan2rpm</tt></a> helps <a
    href="http://web.archive.org/howto/rpm/perl/">convert
    Perl modules into RedHat Package Manager (RPM) files</a>. The resulting <tt
    class="file-glob">*.rpm</tt> packages can be installed via a <a
    href="http://web.archive.org/howto/yum/">local
    Yellowdog Updater, Modified (YUM) server</a>. On Debian, try <tt
    class="cmd">dh-make-perl --install --cpan
    Module::Name</tt>.</li></ul><h2 id="s2"><tt class="cmd">perl</tt>
    Upgrade Bug</h2><p class="info">The first time <a
href="http://search.cpan.org/perldoc/CPAN"
title="Documentation on the CPAN Perl module"><tt
    class="perl-module">CPAN</tt></a> is invoked, it will run through a set of
    questions, such as which <acronym title="Comprehensive Perl Archive
        Network">CPAN</acronym> mirror site to use. Following the questions, <a
        href="http://search.cpan.org/perldoc/CPAN"
        title="Documentation on the CPAN Perl module"><tt
            class="perl-module">CPAN</tt></a> may recommend that you install <a
        href="http://search.cpan.org/perldoc/Bundle::CPAN"
        title="Documentation on the Bundle::CPAN Perl module"><tt
            class="perl-module">Bundle::CPAN</tt></a> or <a
        href="http://search.cpan.org/perldoc/Bundle::libnet"
        title="Documentation on the Bundle::libnet Perl module"><tt
            class="perl-module">Bundle::libnet</tt></a>.  Avoid installing
    these bundles!</p><p class="info">Older versions of <a
        href="http://search.cpan.org/perldoc/CPAN"
        title="Documentation on the CPAN Perl module"><tt
            class="perl-module">CPAN</tt></a> have a bug whereby a new version
    of <tt class="cmd">perl</tt> itself may be installed. To avoid this bug,
    install the latest version of <a
        href="http://search.cpan.org/perldoc/CPAN"
        title="Documentation on the CPAN Perl module"><tt
            class="perl-module">CPAN</tt></a> first. Setting the <tt
        class="code">FTP_PASSIVE=1</tt> environment variable avoids another
    common problem where active File Transfer Protocol (FTP) connections are
    blocked by a local firewall.</p><p class="data-shell"># <kbd>perl -MCPAN -e
        '$ENV{FTP_PASSIVE} = 1; install CPAN'</kbd></p><p class="info">If
    already in the <a
        href="http://search.cpan.org/perldoc/CPAN"
        title="Documentation on the CPAN Perl module"><tt
            class="perl-module">CPAN</tt></a> shell following the preferences
    questions, use:</p><p class="data-shell">cpan&gt; <kbd>install
     CPAN</kbd></p><p class="info">For reference, the bug is that <a
     href="http://search.cpan.org/perldoc/Bundle::CPAN"
     title="Documentation on the Bundle::CPAN Perl module"><tt
         class="perl-module">Bundle::CPAN</tt></a> or <a
     href="http://search.cpan.org/perldoc/Bundle::libnet"
     title="Documentation on the Bundle::libnet Perl module"><tt
         class="perl-module">Bundle::libnet</tt></a> may  list <a
     href="http://search.cpan.org/perldoc/Data::Dumper"
     title="Documentation on the Data::Dumper Perl module"><tt
         class="perl-module">Data::Dumper</tt></a> as a dependency. <a
     href="http://search.cpan.org/perldoc/Data::Dumper"
     title="Documentation on the Data::Dumper Perl module"><tt
         class="perl-module">Data::Dumper</tt></a> is a built-in <tt
     class="cmd">perl</tt> module, so when old versions of <a
     href="http://search.cpan.org/perldoc/CPAN"
     title="Documentation on the CPAN Perl module"><tt
         class="perl-module">CPAN</tt></a> lookup <a
     href="http://search.cpan.org/perldoc/Data::Dumper"
     title="Documentation on the Data::Dumper Perl module"><tt
         class="perl-module">Data::Dumper</tt></a>, they find a new version of
 <tt class="cmd">perl</tt> to install. This bug has been fixed in current
 versions of <a
     href="http://search.cpan.org/perldoc/CPAN"
     title="Documentation on the CPAN Perl module"><tt
         class="perl-module">CPAN</tt></a>.</p><h2 id="s3">Active FTP
         versus Firewalls</h2><p class="info">Network problems may prevent
 access to <acronym title="Comprehensive Perl Archive Network">CPAN</acronym>
 mirror sites. The chief problem will be utilities set to use active <acronym
     title="File Transfer Protocol">FTP</acronym>, which most firewalls block.
 Peruse <a
     href="http://slacksite.com/other/ftp.html">Active
     FTP vs. Passive FTP, a Definitive Explanation</a> for more details. I
 recommend enabling passive <acronym title="File Transfer
     Protocol">FTP</acronym> by default, though this setting will need to be
 done for a variety of utilities <a
     href="http://search.cpan.org/perldoc/CPAN"
     title="Documentation on the CPAN Perl module"><tt
         class="perl-module">CPAN</tt></a> might run, such as <tt
     class="cmd">wget</tt> or <a
     href="http://search.cpan.org/perldoc/Net::FTP"
     title="Documentation on the Net::FTP Perl module"><tt
         class="perl-module">Net::FTP</tt></a>. Alternatives include disabling
 the client firewall to allow active <acronym title="File Transfer
     Protocol">FTP</acronym> connections back from the <acronym title="File
     Transfer Protocol">FTP</acronym> server, or configuring a local <acronym
     title="File Transfer Protocol">FTP</acronym> proxy.</p><p class="info">Set
 the <tt class="code">FTP_PASSIVE</tt> environment variable before running <tt
     class="cmd">cpan</tt>.</p><p class="data-shell"># <kbd>env FTP_PASSIVE=1
     cpan -i Net::FTP</kbd></p><p class="info">During the install of the <tt
     class="code">libnet</tt> distribution, enable passive <acronym title="File
     Transfer Protocol">FTP</acronym>.</p><p class="data"><br />Ah, I see you
 already have installed libnet before.<br /><br />Do you want to modify/update your
 configuration (y|n) ? [no] <kbd class="input">y</kbd><br /><br />Should all FTP
 connections be passive (y|n) ? [no] <kbd class="input">y</kbd></p><p
 class="info">If <a
     href="http://search.cpan.org/perldoc/Net::FTP"
     title="Documentation on the Net::FTP Perl module"><tt
         class="perl-module">Net::FTP</tt></a> is already installed, edit the
 <tt class="file">libnet.cfg</tt> configuration file to use passive <acronym
     title="File Transfer Protocol">FTP</acronym>.</p><p class="data-shell">$
 <kbd>perl -le 'for (@INC) { $_ .= "/".$ARGV[0]; print if -f }'
     Net/libnet.cfg</kbd><br />/usr/local/lib/perl5/5.8.1/Net/libnet.cfg<br />$
 <kbd>grep passive /usr/local/lib/perl5/5.8.1/Net/libnet.cfg</kbd><br />
 'ftp_int_passive' =&gt; 1,</p><p class="info">If <a
     href="http://search.cpan.org/perldoc/Net::FTP"
     title="Documentation on the Net::FTP Perl module"><tt
         class="perl-module">Net::FTP</tt></a> does not work, or certain
 utilities take too long to time out, consider the following options.</p><ul
     class="list"><li><p>Disable <a
         href="http://search.cpan.org/perldoc/Net::FTP"
         title="Documentation on the Net::FTP Perl module"><tt
             class="perl-module">Net::FTP</tt></a>.</p><p class="info">If <a
         href="http://search.cpan.org/perldoc/Net::FTP"
         title="Documentation on the Net::FTP Perl module"><tt
             class="perl-module">Net::FTP</tt></a> does not work, try adding
     the following line to the <tt class="file">CPAN/Config.pm</tt> preferences
     file. More <a
         href="http://nntp.x.perl.org/group/perl.perl5.porters/73929">information
         on <tt class="code">dontload_hash</tt> posted to the <tt
             class="code">perl.perl5.porters</tt> newsgroup</a>.  Also consider
     installing <a
         href="http://search.cpan.org/perldoc/LWP::UserAgent"
         title="Documentation on the LWP::UserAgent Perl module"><tt
             class="perl-module">LWP::UserAgent</tt></a>, which is more capable
     than <a
         href="http://search.cpan.org/perldoc/Net::FTP"
         title="Documentation on the Net::FTP Perl module"><tt
             class="perl-module">Net::FTP</tt></a>.</p><p
     class="data">'dontload_hash' =&gt; { 'Net::FTP' =&gt; 1 },</p></li><li><p>Disable
     utilities that do not work</p><p class="info">To reconfigure <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> to not call certain utilities,
     replace the path to the utility with a single space.</p><p
     class="data-shell">$ <kbd>grep ncftp ~/.cpan/CPAN/MyConfig.pm</kbd><br />
     'ncftp' =&gt; q[ ],<br />  'ncftpget' =&gt; q[ ],</p></li></ul><h2 id="s4">
         Preferences Questions</h2><p class="info"><a
     href="http://search.cpan.org/perldoc/CPAN"
     title="Documentation on the CPAN Perl module"><tt
         class="perl-module">CPAN</tt></a> will ask for preferences settings
 any time the <tt class="file">Config.pm</tt> preferences file does not exist
 or is out of date. The default choice should be acceptable for most.</p><ul
     class="list"><li><p>CPAN build and cache directory? [<tt
         class="file">/root/.cpan</tt>]</p><p class="info">I use <tt
         class="file">/var/spool/cpan</tt>, as the root filesystem tends to be
     small on my systems, and the spool area makes more sense to
     me.</p></li><li><p>Policy on building prerequisites (follow, ask or ignore)?
     [ask]</p><p class="info">Leave this setting set to <kbd
         class="input">ask</kbd> when upgrading <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> the first time, to prevent
     dependency lookups automatically installing the latest stable <tt
         class="cmd">perl</tt>. With <kbd class="input">ask</kbd> set, one can
     say no to queries that ask to install <a
         href="http://search.cpan.org/perldoc/Bundle::CPAN"
         title="Documentation on the Bundle::CPAN Perl module"><tt
             class="perl-module">Bundle::CPAN</tt></a>, <a
         href="http://search.cpan.org/perldoc/Bundle::libnet"
         title="Documentation on the Bundle::libnet Perl module"><tt
             class="perl-module">Bundle::libnet</tt></a>, or <a
         href="http://search.cpan.org/perldoc/Data::Dumper"
         title="Documentation on the Data::Dumper Perl module"><tt
             class="perl-module">Data::Dumper</tt></a> until the latest version
     of <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> is installed.</p></li><li><p>Where is
     your <tt class="file-glob">*</tt> program? [<tt
         class="file-glob">*</tt>]</p><p class="info">This series of questions
     lets one configure (or disable) paths to various utilities <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> may use to download or unpack
     modules. It is safe to leave entries blank, as long as <a
         href="http://search.cpan.org/perldoc/CPAN"
         title="Documentation on the CPAN Perl module"><tt
             class="perl-module">CPAN</tt></a> is left with at least one
     working program that can download modules and another to expand
     them.</p><p class="info">To disable a particular utility, use a single
     space instead of a file path.</p></li><li><p>Parameters for the '<tt
         class="cmd">make install</tt>' command?</p><p class="info">Set this
     option to include <tt class="code">UNINST=1</tt> if installing as root.
     This properly cleans out files from older versions of a module being
     installed.  For user-specific setup, I never set the <tt
         class="code">UNINST</tt> option, to avoid remove warnings of
     unremovable system files.</p></li><li><p>Now we need to know where your favorite
     CPAN sites are located.</p><p class="info">Choose several <acronym
         title="Comprehensive Perl Archive Network">CPAN</acronym> mirror
     sites.  Use <tt class="cmd">traceroute</tt> or bandwidth testing tools to
     determine which mirrors are best for your system. Or, <a
         href="http://cpan.org/misc/cpan-faq.html#How_mirror_CPAN">mirror
         <acronym title="Comprehensive Perl Archive Network">CPAN</acronym> to
         a local system</a>.</p><p class="info">The mirrors list may need to be
updated periodically, if a previous mirror site stops hosting <acronym
    title="Comprehensive Perl Archive Network">CPAN</acronym>. Symptoms of this
will be slow downloads as <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> fails though the mirror
list.</p></li></ul><h2 id="s5">Reconfiguring CPAN</h2><p class="info">To
alter the <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> preferences, either edit the <tt
    class="file">Config.pm</tt> configuration file manually, or use the
following command in the CPAN shell.</p><p class="data-shell">cpan&gt; <kbd>o
    conf init</kbd></p><p class="info">The <tt class="cmd-arg">init</tt>
configuration option runs through all the configuration questions, which may be
time consuming.  For example, other <tt class="cmd">o conf</tt> commands can be
used to list, remove, and add mirror sites, and then to save the changes to
disk.</p><p class="data-shell">cpan&gt; <kbd>o conf urllist</kbd><br />
urllist<br />ftp://ftp.kernel.org/pub/CPAN/<br />Type 'o conf' to view
configuration edit options<br /><br /><br />cpan&gt; <kbd>o conf urllist
    shift</kbd><br /><br />cpan&gt; <kbd>o conf urllist push
    ftp://ftp-mirror.internap.com/pub/CPAN/</kbd><br /><br />cpan&gt; <kbd>o conf
    urllist</kbd><br />    urllist<br />

   <!-- base
   href="http://sial.org.wstub.archive.org/howto/perl/life-with-cpan/" -->

ftp://ftp-mirror.internap.com/pub/CPAN/
        <br />Type 'o conf' to view configuration edit
        options<br /><br /><br />cpan&gt; <kbd>o conf commit</kbd><br />commit: wrote
        /usr/local/lib/perl5/5.6.1/CPAN/Config.pm<br /></p><p class="info">To
        manually edit the existing configuration file, either open the
        user-specific <tt class="file">~/.cpan/CPAN/MyConfig.pm</tt> directly,
        or locate the system-wide configuration file (stored somewhere under
        the <tt class="cmd">perl</tt> <tt class="code">@INC</tt> path list) to
        edit with the following command.</p><p class="data-shell">$ <kbd>perl
            -le 'for (@INC) { $_ .= $ARGV[0]; print if -f }'
            /CPAN/Config.pm</kbd><br />/System/Library/Perl/CPAN/Config.pm</p>
            <h2 id="s6">Usage Tips</h2><div class="subsection"><a
                href="#s6.1">Invocation</a>
            | <a
                href="#s6.2"><tt
                    class="code">autobundle</tt></a> | <a
                href="#s6.3">Old
                Modules</a> | <a
                href="#s6.4">Mac
                OS X</a> | <a
                href="#s6.5">Manual
                Build</a> | <a
                href="#s6.6"><tt
                    class="cmd">sudo</tt></a> | <a
                href="#s6.7">Uninstalling</a>
            | <a
                href="#s6.8">Upgrading</a></div><p
        class="info">Once the latest version of <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> has been installed, it is
        safe to install <a
            href="http://search.cpan.org/perldoc/Bundle::CPAN"
            title="Documentation on the Bundle::CPAN Perl module"><tt
                class="perl-module">Bundle::CPAN</tt></a> (as older versions of
        <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> would attempt to upgrade <tt
            class="cmd">perl</tt> itself). If already in the <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> shell, run <tt
            class="cmd">reload cpan</tt> first.</p><p
        class="data-shell">cpan&gt; <kbd>reload cpan</kbd><br /><br />cpan&gt;
        <kbd>install Bundle::CPAN</kbd></p><p class="info">The following
        sections outline various uses and caveats with <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a>.</p>
                <h3 id="s6.1">Invocation</h3><p class="info">The latest
        version of <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> should install a <tt
            class="cmd">cpan</tt> command somewhere on the system, which is
        easier to use than the traditional means of calling <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a>.  With an up to date version
        of <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a>, the following sets of
        commands are equivalent.  Hereafter, the shorter <tt
            class="cmd">cpan</tt> method will be used.</p><p
        class="data-shell"><span class="comment"># enter the CPAN
            shell</span><br /># <kbd>perl -MCPAN -e shell</kbd><br />#
        <kbd>cpan</kbd><br /><br /><span class="comment"># install the Acme::Bleach
            module</span><br /># <kbd>perl -MCPAN -e install
            Acme::Bleach</kbd><br /># <kbd>cpan -i Acme::Bleach</kbd></p><p
        class="note">Depending on the shell in question, one may need to issue
        the <tt class="cmd">hash -r</tt> or <tt class="cmd">rehash</tt> command
        to make the new <tt class="cmd">cpan</tt> command appear in the search
        path after the latest <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> is installed.  Consult your
        shell’s documentation for more information on whether this is
        required.</p><h3 id="s6.2"><tt
                    class="code">autobundle</tt></h3><p class="info">The <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> <tt
            class="cmd">autobundle</tt> can be used to ease <tt
            class="cmd">perl</tt> upgrades, by creating a special bundle
        containing all the installed modules of the current version of <tt
            class="cmd">perl</tt>.  This bundle can then be installed once the
        new version of <tt class="cmd">perl</tt> is installed.</p><p
        class="data-shell">cpan&gt; <kbd>autobundle</kbd><br /><br /><br />Wrote
        bundle file<br />
        /var/spool/cpan/Bundle/Snapshot_2003_10_01_00.pm<br /><br /><br />cpan&gt;
        <kbd>quit</kbd><br /><br /><span class="comment"># upgrade perl here
</span><br /><br /># <kbd>cpan</kbd><br />cpan&gt; <kbd>install
            Bundle::Snapshot_2003_10_01_00</kbd></p><p class="info">Autobundle
        appears to install the modules in alphabetical order; setting the <tt
            class="code">prerequisites_policy</tt> policy to <tt
            class="code">ask</tt> should help. Multiple install runs may be
        needed to install everything properly. Module build failures will lead
        to much recursion on the part of <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a>.</p><h3 id="s6.3">Old
                Modules</h3><p class="info">Some modules found by <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a> are out of date, and will not
        compile. An updated module may be available on <acronym
            title="Comprehensive Perl Archive Network">CPAN</acronym>, just not
        linked to as “current” by <a
            href="http://search.cpan.org/perldoc/CPAN"
            title="Documentation on the CPAN Perl module"><tt
                class="perl-module">CPAN</tt></a>. Modules known to have this
        problem include the following. The links below should point to the
        current version of the modules.</p><ul class="list"><li> <a
                href="http://search.cpan.org/perldoc/Mail::Cclient"
                title="Documentation on the Mail::Cclient Perl module"><tt
                    class="perl-module">Mail::Cclient</tt></a>
            <br />&nbsp;</li><li> <a
                href="http://search.cpan.org/perldoc/OpenGL"
                title="Documentation on the OpenGL Perl module"><tt
                    class="perl-module">OpenGL</tt></a> </li></ul>
                    <h3 id="s6.4">Mac OS X</h3><p class="info"><a
            href="macosx/">Problems
            with <acronym title="Comprehensive Perl Archive
                Network">CPAN</acronym> on Mac OS X</a>.</p>
                <h3 id="s6.5">Manual Build</h3><p class="info">On occasion one
      may need to manually build or test a module, or consult the module
      directory to read the documentation on any special needs the module may
      have.  This can be done with the <a
          href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> shell <tt class="cmd">look</tt>
command.</p><p class="data-shell">cpan&gt; <kbd>look
    Net::SSLeay</kbd><br /><br />Working directory is
/var/spool/cpan/build/Net_SSLeay.pm-1.25<br /># <kbd>exit</kbd><br />cpan&gt;
<kbd>&nbsp;</kbd></p><h3 id="s6.6"><tt class="cmd">sudo</tt></h3><p
class="info">If <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> is installed in your home directory,
the system-wide <tt class="cmd">cpan</tt> may cause problems when run via <a
    href="http://www.freebsd.org/cgi/man.cgi?query=sudo&amp;sektion=8&amp;manpath=OpenBSD"
    title="FreeBSD man page search for sudo, section 8 on OpenBSD"><tt
        class="man">sudo(8)</tt></a>, as by default <tt class="cmd">sudo</tt>
will invoke <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> using the <tt
    class="file">~/.cpan/CPAN/MyConfig.pm</tt> configuration, but as <tt
    class="code">root</tt>, which causes no end of trouble.  To avoid this
problem, reset the <tt class="code">HOME</tt> environment variable with the <tt
    class="cmd-arg">-H</tt> option to <tt class="cmd">sudo</tt> when invoking
<a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a>.</p><p class="data-shell">$ <kbd>sudo
    -H cpan</kbd></p><h3 id="s6.7">Uninstalling</h3><p class="info"><a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> itself offers no uninstall method.
Several of the alternatives to <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> do, such as <a
    href="http://search.cpan.org/perldoc/CPANPLUS"
    title="Documentation on the CPANPLUS Perl module"><tt
        class="perl-module">CPANPLUS</tt></a> or vendor package/port systems.
If the module has been fully installed along with a <tt
    class="file">.packlist</tt> file for the module, the <a
    href="http://search.cpan.org/perldoc/ExtUtils::Packlist"
    title="Documentation on the ExtUtils::Packlist Perl module"><tt
        class="perl-module">ExtUtils::Packlist</tt></a> perl module
documentation includes code for a <tt class="cmd">modrm</tt> command to cleanly
remove an installed module.</p><p class="note">Modules built with other tools,
such as <a
    href="http://search.cpan.org/perldoc/Module::Build"
    title="Documentation on the Module::Build Perl module"><tt
        class="perl-module">Module::Build</tt></a>, may not write out a <tt
    class="file">.packlist</tt> file for use by <a
    href="http://search.cpan.org/perldoc/ExtUtils::Packlist"
    title="Documentation on the ExtUtils::Packlist Perl module"><tt
        class="perl-module">ExtUtils::Packlist</tt></a>.</p><h3 id="s6.9">
    Upgrading</h3><p class="info">How to upgrade all the
modules on the system like <tt class="cmd">apt-get</tt> is actually documented
in the <a
    href="http://search.cpan.org/perldoc/CPAN"
    title="Documentation on the CPAN Perl module"><tt
        class="perl-module">CPAN</tt></a> manual; however, the question comes
up often enough that I answer it here as well.</p><p class="data-shell"><span
    class="comment"># install everything that is outdated on my
    disk:</span><br /># <kbd>perl -MCPAN -e
    'CPAN::Shell-&gt;install(CPAN::Shell-&gt;r)'</kbd></p><p
class="info">Problems with this include new versions of modules that may break
old module behavior, or various modules that cannot be upgraded due to build
failures or system incompatibilities. Best to subject a test system to this
sort of mass module
 upgrade before attempting it on a production system.</p><h2 id="s7">
         Debugging Module Build Problems</h2><p class="info">See
 the <a
     href="debug/">Debugging
     CPAN Build Problems</a> guide for more information.</p><h2 id="s8">
         Using CPAN with a non-root account</h2><p
 class="info"><a
     href="non-root/">Notes
     on using CPAN with a non-root account</a>, or installing Perl modules to
 directories besides the default system areas, such as a software depot or
 under <tt class="code">$HOME</tt>. Consider also <a
     href="http://search.cpan.org/perldoc/local::lib"
     title="Documentation on the local::lib Perl module"><tt
         class="perl-module">local::lib</tt></a> to bootsrap custom Perl module
 installation directories.</p><div class="footer">
    <p><a
         href="http://web.archive.org/contact/">Questions
         or comments about this page?</a> Current ruminations available on <a
         href="http://web.archive.org/blog/">my
         blog</a>.  </p><p><tt>$Id: index.xml,v 1.46 2007/12/11 03:04:58 jmates
         Exp $</tt></p></div></div> </body><!-- SOME META URL'S ON THIS PAGE
         HAVE BEEN REWRITTEN BY THE WAYBACK MACHINE OF THE INTERNET ARCHIVE IN
         ORDER TO PRESERVE THE TEMPORAL INTEGRITY OF THE SESSION. --><!-- SOME
         LINK HREF'S ON THIS PAGE HAVE BEEN REWRITTEN BY THE WAYBACK MACHINE OF
         THE INTERNET ARCHIVE IN ORDER TO PRESERVE THE TEMPORAL INTEGRITY OF
         THE SESSION. --></html>