From 0f6c29a392b4157cbbd8c7f5f492c8b4b0261c0a Mon Sep 17 00:00:00 2001
From: Nelson Elhage <nelhage@mit.edu>
Date: Sun, 20 Dec 2009 11:08:15 -0500
Subject: [PATCH] Document local::lib

---
 doc/cpan.mdwn | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/cpan.mdwn b/doc/cpan.mdwn
index 4c9ca30..fb6a971 100644
--- a/doc/cpan.mdwn
+++ b/doc/cpan.mdwn
@@ -22,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`.
 
+## 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.4.9][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/~apeiron/local-lib-1.004009/lib/local/lib.pm "local::lib"
+[lltgz]: http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.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:
@@ -44,3 +61,15 @@ By default, CPAN prompts you whether or not to follow dependencies when installi
     cpan> o conf prerequisites_policy follow
     cpan> o conf commit
     cpan> install Some::Module
+
+### Installing packages into a directory
+    $ wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.004009.tar.gz
+    $ tar xzf local-lib-1.004009.tar.gz
+    $ cd local-lib-1.004009/
+    $ 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
+    cpan> o conf prerequisites_policy follow
+    cpan> o conf commit
+    cpan> install Some::Module
-- 
2.44.0