Document some gotchas using CPAN and local::lib on Athena.

[wiki.git] / doc / cpan.mdwn

diff --git a/doc/cpan.mdwn b/doc/cpan.mdwn
index fb6a9712fe956aa69de48ad9e4a5c31f7a808ba0..33ccdde9f7a844e22ef051dfd6e224835d1ee5e2 100644 (file)
--- a/doc/cpan.mdwn
+++ b/doc/cpan.mdwn
@@ -47,7 +47,20 @@ 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
 
-   `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) on CPAN). 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://search.cpan.org/~dapm/perl-5.10.1/lib/filetest.pm
 
 
 ## Cheat-sheet
@@ -56,6 +69,7 @@ By default, CPAN prompts you whether or not to follow dependencies when installi
 ### 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
@@ -70,6 +84,7 @@ By default, CPAN prompts you whether or not to follow dependencies when installi
     $ 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