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 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 filesystem.  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} module aims to ease the process of making a GNU
  24 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} 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} 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} 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 If your package installs shell scripts, also import the
  93 @code{relocatable-script} module.  Then, near the beginning of each
  94 shell script that your package installs, add the following:
  95
  96 @example
  97 @@relocatable_sh@@
  98 if test "@@RELOCATABLE@@" = yes; then
  99   exec_prefix="@@exec_prefix@@"
 100   bindir="@@bindir@@"
 101   orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
 102   func_find_curr_installdir # determine curr_installdir
 103   func_find_prefixes
 104   # Relocate the directory variables that we use.
 105   gettext_dir=`echo "$gettext_dir/" | sed -e
 106 "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" | sed -e 's,/$,,'`
 107 fi
 108 @end example
 109
 110 You must adapt the definition of @code{orig_installdir}, depending on
 111 where the script gets installed.  Also, at the end, instead of
 112 @code{gettext_dir}, transform those variables that you need.
 113
 114 @item
 115 In your @file{Makefile.am}, for every program @command{foo} that gets
 116 installed in, say, @file{$(bindir)}, you add:
 117
 118 @example
 119 foo_CPPFLAGS = -DINSTALLDIR=\"$(bindir)\"
 120 if RELOCATABLE_VIA_LD
 121 foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
 122 endif
 123 @end example
 124
 125 @item
 126 You may also need to add one or two variable assignments to your
 127 @file{configure.ac}.
 128
 129 If your package (or any package you rely on, e.g.@: gettext-runtime)
 130 will be relocated together with a set of installed shared libraries,
 131 then set @var{RELOCATABLE_LIBRARY_PATH} to a colon-separated list
 132 of those libraries' directories, e.g.
 133 @example
 134 RELOCATABLE_LIBRARY_PATH='$(libdir)'
 135 @end example
 136
 137 If your @file{config.h} is not in @file{$(top_builddir)}, then set
 138 @var{RELOCATABLE_CONFIG_H_DIR} to its directory, e.g.
 139 @example
 140 RELOCATABLE_CONFIG_H_DIR='$(top_builddir)/src'
 141 @end example
 142 @end enumerate