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