doc/relocatable.texi

   1 @node Enabling Relocatability
   2 @section Enabling Relocatability
   3
   4 It has been a pain for many users of GNU packages for a long time that
   5 packages are not relocatable.  It means a user cannot copy a program,
   6 installed by another user on the same machine, to his home directory,
   7 and have it work correctly (including i18n).  So many users need to go
   8 through @code{configure; make; make install} with all its
   9 dependencies, options, and hurdles.
  10
  11 Most package management systems, that allow the user to install
  12 pre-built binaries of the packages, solve the ``ease of
  13 installation'' problem, but they hardwire path names, usually to
  14 @file{/usr} or @file{/usr/local}.  This means that users need root
  15 privileges to install a binary package, and prevents installing two
  16 different versions of the same binary package.
  17
  18 A relocatable program can be moved or copied to a different location
  19 on the file system.  It is possible to make symlinks to the installed
  20 and moved programs, and invoke them through the symlink. It is
  21 possible to do the same thing with a hard link @emph{only} if the hard
  22 link file is in the same directory as the real program.
  23
  24 To configure a program to be relocatable, add
  25 @option{--enable-relocatable} to the @command{configure} command line.
  26
  27 On some OSes the executables remember the location of shared libraries
  28 and prefer them over any other search path.  Therefore, such an
  29 executable will look for its shared libraries first in the original
  30 installation directory and only then in the current installation
  31 directory.  Thus, for reliability, it is best to also give a
  32 @option{--prefix} option pointing to a directory that does not exist
  33 now and which never will be created, e.g.@:
  34 @option{--prefix=/nonexistent}.  You may use
  35 @code{DESTDIR=@var{dest-dir}} on the @command{make} command line to
  36 avoid installing into that directory.
  37
  38 We do not recommend using a prefix writable by unprivileged users
  39 (e.g.@: @file{/tmp/inst$$}) because such a directory can be recreated
  40 by an unprivileged user after the original directory has been removed.
  41 We also do not recommend prefixes that might be behind an automounter
  42 (e.g.@: @file{$HOME/inst$$}) because of the performance impact of
  43 directory searching.
  44
  45 Here's a sample installation run that takes into account all these
  46 recommendations:
  47
  48 @example
  49 ./configure --enable-relocatable --prefix=/nonexistent
  50 make
  51 make install DESTDIR=/tmp/inst$$
  52 @end example
  53
  54 Installation with @option{--enable-relocatable} will not work for
  55 setuid or setgid executables, because such executables search only
  56 system library paths for security reasons.
  57
  58 The runtime penalty and size penalty are negligible on GNU/Linux (just
  59 one system call more when an executable is launched), and small on
  60 other systems (the wrapper program just sets an environment variable
  61 and executes the real program).