update gutenbach url

[wiki.git] / doc / cpan.mdwn

diff --git a/doc/cpan.mdwn b/doc/cpan.mdwn
index fd1346b042a90ff4fd41d5228b6e6a1dc63b604a..3e15bddb17f281f9669bfd863ecb945c597ac052 100644 (file)
--- a/doc/cpan.mdwn
+++ b/doc/cpan.mdwn
@@ -1,5 +1,7 @@
 [[!meta title="Using CPAN"]]
 
 [[!meta title="Using CPAN"]]
 

+If you're mostly familiar with this document, and just want the incants, skip to the <a href="#cheatsheet">cheat sheet</a>.
+

 [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.
 
 ## Is it in my distribution?
 [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.
 
 ## Is it in my distribution?


@@ -10,17 +12,6 @@ If you are running Debian or Ubuntu, the Perl module `Foo::Bar` will be present,
 
     yum whatprovides 'perl(Foo::Bar)'
 
 
     yum whatprovides 'perl(Foo::Bar)'
 

-## The short version (installing packages system-wide)
-
-If you want some more explanation, skip to the next section. This section is meant as a cheat-sheet for people who just want to remember the various incants. This assumes you want to install packages system-wide on the local system, and are a sudoer.
-
-    $ env PERL_MM_USE_DEFAULT=1 cpan
-    cpan> o conf make_install_make_command '/usr/bin/sudo /usr/bin/make'
-    cpan> o conf mbuild_install_build_command '/usr/bin/sudo ./Build'
-    cpan> o conf prerequisites_policy follow
-    cpan> o conf commit
-    cpan> install Some::Module
-

 ## Installing packages system-wide
 
 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:
 ## Installing packages system-wide
 
 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:


@@ -31,6 +22,23 @@ The easiest way to use CPAN is to install packages system-wide. Run `cpan` as yo
 
 You should now be able to install a package with `install Package`.
 
 
 You should now be able to install a package with `install Package`.
 

+## Installing packages locally
+
+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).
+
+ * Grab the latest `local::lib` tarball from CPAN (As of this writing, that's version [1.008004][lltgz])
+ * Unpack the tarball and run
+
+        perl Makefile.PL --bootstrap=/path/to/install/
+        make && make install
+
+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.
+
+For more details, such as how to manage multiple different `local::lib` installations, see `local::lib`'s [documentation on CPAN][local::lib]
+
+[local::lib]: http://search.cpan.org/perldoc?local::lib "local::lib"
+[lltgz]: http://www.cpan.org/modules/by-module/lib/local-lib-1.008004.tar.gz
+

 ## Automatically installing dependencies
 
 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:
 ## Automatically installing dependencies
 
 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:


@@ -39,6 +47,44 @@ By default, CPAN prompts you whether or not to follow dependencies when installi
  * Set the environment variable `PERL_MM_USE_DEFAULT` to `1`.
    e.g. run `cpan` as
 
  * Set the environment variable `PERL_MM_USE_DEFAULT` to `1`.
    e.g. run `cpan` as
 

-   `env PERL_MM_USE_DEFAULT=1 cpan`
+       env PERL_MM_USE_DEFAULT=1 cpan
+
+
+## Gotchas using CPAN on Athena

 
 

+ * For whatever reason, perl believes itself to be smarter than your operating system by default, and checks permissions by looking at the permission bits on files, rather than using `access(2)`. (See [filetest][filetest] in the Perl docs.) Furthermore, when installing modules, CPAN checks to see if you have write permissions on the destination, and aborts if it doesn't think you do, without even trying. I have been unable to find a way to override either of these behaviors.

 
 

+  This is a problem in AFS for obvious reasons, since AFS does not use UNIX permissions. I happen to only need to install perl modules into lockers on which I am the owner; If you need to install things somewhere where the UNIX permission bits indicate you would not have access, you're out of luck as far as I can tell.
+
+ * Sharing a `local::lib` installation dir across multiple platforms is not recommended. While perl **does** include the architecture and sysname (e.g. `x86_64-linux-gnu-thread-multi/`) in the path when installing `.so` files for modules written in XS, it **does not** do the same for the version of Perl itself. So while you can share a single installation directory between 32- and 64-bit platforms, or between Linux and Solaris, all kinds of things will go wrong if you try to share it between a 32-bit perl 5.8 and a 32-bit perl 5.10 on the same platform.
+
+I work around this for BarnOwl by having completely separate perl module installs for every AFS sysname we support. This is painful to maintain, but I've found it to be the most reliable option.
+
+[filetest]: http://perldoc.perl.org/filetest.html
+
+
+## Cheat-sheet
+<a name="cheatsheet" />
+
+### Installing packages system-wide
+
+    $ env PERL_MM_USE_DEFAULT=1 cpan
+    # Answer 'yes' if CPAN asks to configure itself automatically
+    cpan> o conf make_install_make_command '/usr/bin/sudo /usr/bin/make'
+    cpan> o conf mbuild_install_build_command '/usr/bin/sudo ./Build'
+    cpan> o conf prerequisites_policy follow
+    cpan> o conf commit
+    cpan> install Some::Module
+
+### Installing packages into a directory
+    $ wget http://www.cpan.org/modules/by-module/lib/local-lib-1.008004.tar.gz
+    $ tar xzf local-lib-1.008004.tar.gz
+    $ cd local-lib-1.008004/
+    $ perl Makefile.PL --bootstrap=/install/dir/
+    $ make && make install
+    $ eval $(perl -I/install/dir/lib/perl5/ -Mlocal::lib)
+    $ env PERL_MM_USE_DEFAULT=1 cpan
+    # Answer 'yes' if CPAN asks to configure itself automatically
+    cpan> o conf prerequisites_policy follow
+    cpan> o conf commit
+    cpan> install Some::Module