doc/relocatable-maint.texi

   1 @node Supporting Relocation
   2 @section Supporting Relocation
   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 other binary distributions 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 The @code{relocatable-prog} module aims to ease the process of making a
  24 GNU program relocatable.  It helps overcome two obstacles.  First, it aids
  25 with relocating the hard-coded references to absolute file names that
  26 GNU programs often contain.  These references must be fixed up at
  27 runtime if a program is to be successfully relocated.  The
  28 @code{relocatable-prog} module provides a function @code{relocate} that
  29 does this job.
  30
  31 Second, the loader must be able to find shared libraries linked to
  32 relocatable executables or referenced by other shared libraries linked
  33 to relocatable executables.  The @code{relocatable-prog} module helps out
  34 here in a platform-specific way:
  35
  36 @itemize
  37 @item
  38 On GNU/Linux, it adds a linker option (@option{-rpath}) that causes
  39 the dynamic linker to search for libraries in a directory relative to
  40 the location of the invoked executable.
  41
  42 @item
  43 On other Unix systems, it installs a wrapper executable.  The wrapper
  44 sets the environment variable that controls shared library searching
  45 (usually @env{LD_LIBRARY_PATH}) and then invokes the real executable.
  46
  47 This approach does not always work.  On OpenBSD and OpenServer,
  48 prereleases of Libtool 1.5 put absolute file names of libraries in
  49 executables, which prevents searching any other locations.
  50
  51 @item
  52 On Windows, the executable's own directory is searched for libraries,
  53 so installing shared libraries into the executable's directory is
  54 sufficient.
  55 @end itemize
  56
  57 You can make your program relocatable by following these steps:
  58
  59 @enumerate
  60 @item
  61 Import the @code{relocatable-prog} module.
  62
  63 @item
  64 In every program, add to @code{main} as the first statement (even
  65 before setting the locale or doing anything related to libintl):
  66
  67 @example
  68 set_program_name (argv[0]);
  69 @end example
  70
  71 The prototype for this function is in @file{progname.h}.
  72
  73 @item
  74 Everywhere where you use a constant pathname from installation-time,
  75 wrap it in @code{relocate} so it gets translated to the run-time situation.
  76 Example:
  77
  78 @example
  79 bindtextdomain (PACKAGE, LOCALEDIR);
  80 @end example
  81
  82 @noindent
  83 becomes:
  84
  85 @example
  86 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
  87 @end example
  88
  89 The prototype for this function is in @file{relocatable.h}.
  90
  91 @item
  92 The @code{set_program_name} function can also configure some
  93 additional libraries to relocate files that they access, by defining
  94 corresponding C preprocessor symbols to 1.  The libraries for which
  95 this is supported and the corresponding preprocessor symbols are:
  96
  97 @table @asis
  98 @item libcharset
  99 @code{DEPENDS_ON_LIBCHARSET}
 100
 101 @item libiconv
 102 @code{DEPENDS_ON_LIBICONV}
 103
 104 @item libintl
 105 @code{DEPENDS_ON_LIBINTL}
 106 @end table
 107
 108 Defining the symbol for a library makes every program in the package
 109 depend on that library, whether the program really uses the library or
 110 not, so this feature should be used with some caution.
 111
 112 @item
 113 If your package installs shell scripts, also import the
 114 @code{relocatable-script} module.  Then, near the beginning of each
 115 shell script that your package installs, add the following:
 116
 117 @example
 118 @@relocatable_sh@@
 119 if test "@@RELOCATABLE@@" = yes; then
 120   exec_prefix="@@exec_prefix@@"
 121   bindir="@@bindir@@"
 122   orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
 123   func_find_curr_installdir # determine curr_installdir
 124   func_find_prefixes
 125   relocate () @{
 126     echo "$1/" \
 127     | sed -e "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" \
 128     | sed -e 's,/$,,'
 129   @}
 130 else
 131   relocate () @{
 132     echo "$1"
 133   @}
 134 fi
 135
 136 # Get some relocated directory names.
 137 sysconfdir=`relocate "@@sysconfdir@@"`
 138 some_datadir=`relocate "@@datadir@@/something"`
 139 @end example
 140
 141 You must adapt the definition of @code{orig_installdir}, depending on
 142 where the script gets installed.  Also, at the end, instead of
 143 @code{sysconfdir} and @code{some_datadir}, transform those variables
 144 that you need.
 145
 146 @item
 147 In your @file{Makefile.am}, for every program @command{foo} that gets
 148 installed in, say, @file{$(bindir)}, you add:
 149
 150 @example
 151 foo_CPPFLAGS = -DINSTALLDIR=\"$(bindir)\"
 152 if RELOCATABLE_VIA_LD
 153 foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
 154 endif
 155 @end example
 156
 157 @item
 158 You may also need to add a couple of variable assignments to your
 159 @file{configure.ac}.
 160
 161 If your package (or any package you rely on, e.g.@: gettext-runtime)
 162 will be relocated together with a set of installed shared libraries,
 163 then set @var{RELOCATABLE_LIBRARY_PATH} to a colon-separated list
 164 of those libraries' directories, e.g.
 165 @example
 166 RELOCATABLE_LIBRARY_PATH='$(libdir)'
 167 @end example
 168
 169 If your @file{config.h} is not in @file{$(top_builddir)}, then set
 170 @var{RELOCATABLE_CONFIG_H_DIR} to its directory, e.g.
 171 @example
 172 RELOCATABLE_CONFIG_H_DIR='$(top_builddir)/src'
 173 @end example
 174 @end enumerate