Document local::lib
authorNelson Elhage <nelhage@mit.edu>
Sun, 20 Dec 2009 16:08:15 +0000 (11:08 -0500)
committersipb-www <sipb-www@busy-beaver.mit.edu>
Sun, 20 Dec 2009 16:08:15 +0000 (11:08 -0500)
doc/cpan.mdwn

index 4c9ca306a42273daadb4be130cc6edd106aeca75..fb6a9712fe956aa69de48ad9e4a5c31f7a808ba0 100644 (file)
@@ -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