doc/cpan.mdwn

   1 [[!meta title="Using CPAN"]]
   2
   3 If you're mostly familiar with this document, and just want the incants, skip to the <a href="#cheatsheet">cheat sheet</a>.
   4
   5 [CPAN](http://cpan.org) is the "Comprehensive Perl Archive Network", a repository of useful Perl modules. Most projects written in Perl depend on at least one module from CPAN, and dependency graphs of dozens of modules are not uncommon. Unfortunately, installing CPAN modules can be somewhat tricky, in part due to the age of many of the tools involved. This document is designed to help someone who is not a Perl programmer learn how to get a CPAN module or set of modules installed with a minimum of pain.
   6
   7 ## Is it in my distribution?
   8
   9 Most popular Linux distributions package a large number of CPAN modules as part of the distribution. If a sufficiently new version of the package you want is available from your distribution, this is likely to be a better option than installing it from CPAN.
  10
  11 If you are running Debian or Ubuntu, the Perl module `Foo::Bar` will be present, if at all, under the name `libfoo-bar-perl`. On Fedora, it will be named `perl-Foo-Bar`, or can be found with the query
  12
  13     yum whatprovides 'perl(Foo::Bar)'
  14
  15 ## Installing packages system-wide
  16
  17 The easiest way to use CPAN is to install packages system-wide. Run `cpan` as your user, and then enter the following commands to configure CPAN to use `sudo` to get root privileges to install packages:
  18
  19     o conf make_install_make_command '/usr/bin/sudo /usr/bin/make'
  20     o conf mbuild_install_build_command '/usr/bin/sudo ./Build'
  21     o conf commit
  22
  23 You should now be able to install a package with `install Package`.
  24
  25 ## Installing packages locally
  26
  27 If you don't have root access, just want to install packages for your own use, or want to install packages into AFS for use from multiple systems, you want [`local::lib`][local::lib]. (It's possible to configure CPAN to do this by hand, but trust me, `local::lib` is easier).
  28
  29  * Grab the latest `local::lib` tarball from CPAN (As of this writing, that's version [1.4.9][lltgz])
  30  * Unpack the tarball and run
  31
  32         perl Makefile.PL --bootstrap=/path/to/install/
  33         make && make install
  34
  35 You can now run `perl -I/path/to/install/lib/perl5/ -Mlocal::lib` to get a fragment of shell code you should run to set up your environment to both use perl modules from your install, and to tell `cpan` to install there.
  36
  37 For more details, such as how to manage multiple different `local::lib` installations, see `local::lib`'s [documentation on CPAN][local::lib]
  38
  39 [local::lib]: http://search.cpan.org/~apeiron/local-lib-1.004009/lib/local/lib.pm "local::lib"
  40 [lltgz]: http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.tar.gz
  41
  42 ## Automatically installing dependencies
  43
  44 By default, CPAN prompts you whether or not to follow dependencies when installing a package. This is not usually what you want -- if you want a specific package, you don't care what CPAN has to install to get it to you, so it should do so automatically. There are two steps required to get CPAN to do this:
  45
  46  * Set `prerequisites_policy` to `follow` inside CPAN (`o conf prerequisites_policy follow` and then `o conf commit`)
  47  * Set the environment variable `PERL_MM_USE_DEFAULT` to `1`.
  48    e.g. run `cpan` as
  49
  50    `env PERL_MM_USE_DEFAULT=1 cpan`
  51
  52
  53 ## Cheat-sheet
  54 <a name="cheatsheet" />
  55
  56 ### Installing packages system-wide
  57
  58     $ env PERL_MM_USE_DEFAULT=1 cpan
  59     cpan> o conf make_install_make_command '/usr/bin/sudo /usr/bin/make'
  60     cpan> o conf mbuild_install_build_command '/usr/bin/sudo ./Build'
  61     cpan> o conf prerequisites_policy follow
  62     cpan> o conf commit
  63     cpan> install Some::Module
  64
  65 ### Installing packages into a directory
  66     $ wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.tar.gz
  67     $ tar xzf local-lib-1.004009.tar.gz
  68     $ cd local-lib-1.004009/
  69     $ perl Makefile.PL --bootstrap=/install/dir/
  70     $ make && make install
  71     $ eval $(perl -I/install/dir/lib/perl5/ -Mlocal::lib)
  72     $ env PERL_MM_USE_DEFAULT=1 cpan
  73     cpan> o conf prerequisites_policy follow
  74     cpan> o conf commit
  75     cpan> install Some::Module