Update section about relocatable installation.

1 files changed, 59 insertions, 32 deletions

diff --git a/INSTALL b/INSTALL
index 277728e..2b442ed 100644
--- a/INSTALL
+++ b/INSTALL
@@ -106,38 +106,65 @@ you can set and what kinds of files go in them.
 with an extra prefix or suffix on their names by giving `configure' the
 option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
 
-Relocatable Installation
-========================
-
-   By default, `make install' will install a package with hardwired
-file names, and the package will not work correctly when copied or
-moved to a different location in the filesystem.
-
-   Some packages pay attention to the `--enable-relocatable' option to
-`configure'.  This option makes the entire installed package
-relocatable.  This means, it can be moved or copied to a different
-location on the filesystem.  It is possible to make symlinks to the
-installed and moved programs, and invoke them through the symlink.  It
-is possible to do the same thing  with a hard link _only_ if the hard
-linked file is in the same directory as the real program.
-
-   For reliability it is best to give together with --enable-relocatable
-a `--prefix' option pointing to an otherwise unused (and never used
-again) directory, for example, `--prefix=/tmp/inst$$'.  This is
-recommended because on some OSes the executables remember the location
-of shared libraries (and prefer them over LD_LIBRARY_PATH !), therefore
-such an executable will look for its shared libraries first in the
-original installation directory and only then in the current
-installation directory.
-
-   Installation with `--enable-relocatable' will not work for setuid /
-setgid executables.  (This is because such an executable kills its
-LD_LIBRARY_PATH variable when it is launched.)
-
-   The runtime penalty and size penalty are nearly zero on Linux 2.2 or
-newer (just one system call more when an executable is launched), and
-small on other systems (the wrapper program just sets an environment
-variable and execs the real program).
+Enabling Relocatability
+=======================
+
+   It has been a pain for many users of GNU packages for a long time
+that packages are not relocatable.  It means a user cannot copy a
+program, installed by another user on the same machine, to his home
+directory, and have it work correctly (including i18n).  So many users
+need to go through `configure; make; make install' with all its
+dependencies, options, and hurdles.
+
+   Red Hat, Debian, and similar package systems solve the "ease of
+installation" problem, but they hardwire path names, usually to `/usr'
+or `/usr/local'.  This means that users need root privileges to install
+a binary package, and prevents installing two different versions of the
+same binary package.
+
+   A relocatable program can be moved or copied to a different location
+on the filesystem.  It is possible to make symlinks to the installed
+and moved programs, and invoke them through the symlink. It is possible
+to do the same thing with a hard link _only_ if the hard link file is
+in the same directory as the real program.
+
+   To configure a program to be relocatable, add `--enable-relocatable'
+to the `configure' command line.
+
+   On some OSes the executables remember the location of shared
+libraries and prefer them over any other search path.  Therefore, such
+an executable will look for its shared libraries first in the original
+installation directory and only then in the current installation
+directory.  Thus, for reliability, it is best to also give a `--prefix'
+option pointing to a directory that does not exist now and which never
+will be created, e.g.  `--prefix=/nonexistent'.  You may use
+`DESTDIR=DEST-DIR' on the `make' command line to avoid installing into
+that directory.
+
+   We do not recommend using a prefix writable by unprivileged users
+(e.g. `/tmp/inst$$') because such a directory can be recreated by an
+unprivileged user after the original directory has been removed.  We
+also do not recommend prefixes that might be behind an automounter
+(e.g. `$HOME/inst$$') because of the performance impact of directory
+searching.
+
+   Here's a sample installation run that takes into account all these
+recommendations:
+
+     ./configure --enable-relocatable --prefix=/nonexistent
+     make
+     make install DESTDIR=/tmp/inst$$
+
+   Installation with `--enable-relocatable' will not work for setuid or
+setgid executables, because such executables search only system library
+paths for security reasons.  Also, installation with
+`--enable-relocatable' might not work on OpenBSD, when the package
+contains shared libraries and libtool versions 1.5.xx are used.
+
+   The runtime penalty and size penalty are negligible on GNU/Linux
+(just one system call more when an executable is launched), and small on
+other systems (the wrapper program just sets an environment variable
+and executes the real program).
 
 Optional Features
 =================