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 @item
  48 On Windows, the executable's own directory is searched for libraries,
  49 so installing shared libraries into the executable's directory is
  50 sufficient.
  51 @end itemize
  52
  53 You can make your program relocatable by following these steps:
  54
  55 @enumerate
  56 @item
  57 Import the @code{relocatable-prog} module.  For libraries, use the
  58 @code{relocatable-lib} or @code{relocatable-lib-lgpl} module.
  59 If you need more than one module, or you need to use them with different
  60 settings, you will need multiple copies of gnulib (@pxref{Multiple instances}).
  61
  62 @item
  63 In every program, add to @code{main} as the first statement (even
  64 before setting the locale or doing anything related to libintl):
  65
  66 @example
  67 set_program_name (argv[0]);
  68 @end example
  69
  70 The prototype for this function is in @file{progname.h}.
  71
  72 @item
  73 If you want your code to be portable to platforms that do not support
  74 automatic initialization, call @code{set_relocation_prefix}.
  75
  76 @item
  77 Everywhere where you use a constant pathname from installation-time,
  78 wrap it in @code{relocate} so it gets translated to the run-time situation.
  79 Example:
  80
  81 @example
  82 bindtextdomain (PACKAGE, LOCALEDIR);
  83 @end example
  84
  85 @noindent
  86 becomes:
  87
  88 @example
  89 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
  90 @end example
  91
  92 The prototype for this function is in @file{relocatable.h}.
  93
  94 There is also a variant of this function, named @code{relocate2}, that
  95 makes it easy to reclaim the memory allocated by the call.
  96
  97 @item
  98 The @code{set_program_name} function can also configure some
  99 additional libraries to relocate files that they access, by defining
 100 corresponding C preprocessor symbols to 1.  The libraries for which
 101 this is supported and the corresponding preprocessor symbols are:
 102
 103 @table @asis
 104 @item libcharset
 105 @code{DEPENDS_ON_LIBCHARSET}
 106
 107 @item libiconv
 108 @code{DEPENDS_ON_LIBICONV}
 109
 110 @item libintl
 111 @code{DEPENDS_ON_LIBINTL}
 112 @end table
 113
 114 Defining the symbol for a library makes every program in the package
 115 depend on that library, whether the program really uses the library or
 116 not, so this feature should be used with some caution.
 117
 118 @item
 119 If your package installs shell scripts, also import the
 120 @code{relocatable-script} module.  Then, near the beginning of each
 121 shell script that your package installs, add the following:
 122
 123 @smallexample
 124 @@relocatable_sh@@
 125
 126 prefix="@@prefix@@"
 127 exec_prefix="@@exec_prefix@@"   # usually needs $prefix.
 128 datarootdir="@@datarootdir@@"   # usually needs $prefix.
 129
 130 if test "@@RELOCATABLE@@" = yes; then
 131   bindir="@@bindir@@"
 132   orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
 133   func_find_curr_installdir # determine curr_installdir
 134   func_find_prefixes
 135   relocate () @{
 136     echo "$1/" \
 137     | sed -e "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" \
 138     | sed -e 's,/$,,'
 139   @}
 140 else
 141   relocate () @{
 142     echo "$1"
 143   @}
 144 fi
 145
 146 # Get some relocated directory names.
 147 sysconfdir=`relocate "@@sysconfdir@@"`          # usually needs $prefix.
 148 some_datadir=`relocate "@@datadir@@/something"` # usually needs $datarootdir.
 149 bindir=`relocate "@@bindir@@"`       # usually needs $exec_prefix, hence $prefix.
 150 @end smallexample
 151
 152 You must adapt the definition of @code{orig_installdir}, depending on
 153 where the script gets installed.  Also, at the end, instead of
 154 @code{sysconfdir} and @code{some_datadir}, transform those variables
 155 that you need.
 156
 157 @item
 158 If your package installs Perl scripts, also import the
 159 @code{relocatable-perl} module.  Then, near the beginning of each
 160 Perl script that your package installs, add the following:
 161
 162 @smallexample
 163 @@relocatable_pl@@
 164 if ("@@RELOCATABLE@@" eq "yes") @{
 165   my $exec_prefix = "@@exec_prefix@@";
 166   my $orig_installdir = "@@bindir@@"; # see Makefile.am's *_SCRIPTS variables
 167   my ($orig_installprefix, $curr_installprefix) =
 168     find_prefixes($orig_installdir, find_curr_installdir());
 169
 170   # the subroutine is defined whether or not the enclosing block is executed
 171   sub relocate @{
 172     my ($dir) = @@_;
 173     if ("@@RELOCATABLE@@" eq "yes") @{
 174       $dir =~ s%^$orig_installprefix/%$curr_installprefix/%;
 175       $dir =~ s,/$,,;
 176     @}
 177     return $dir;
 178   @}
 179 @}
 180
 181 # Get some relocated directory names.
 182 # (The gnulib module 'configmake' can help with this.)
 183 $sysconfdir = relocate("@@sysconfdir@@");
 184 $some_datadir = relocate(@@datadir@@/something");
 185 @end smallexample
 186
 187 You must adapt the definition of @code{$orig_installdir}, depending on
 188 where the script gets installed.  Also, at the end, instead of
 189 @code{sysconfdir} and @code{some_datadir}, transform those variables
 190 that you need.
 191
 192 @item
 193 In your @file{Makefile.am}, for every program @command{foo} that gets
 194 installed in, say, @file{$(bindir)}, you add:
 195
 196 @example
 197 foo_CPPFLAGS = -DINSTALLDIR=\"$(bindir)\"
 198 if RELOCATABLE_VIA_LD
 199 foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
 200 endif
 201 @end example
 202
 203 When building gnulib to use with a relocatable library, you need to
 204 define the preprocessor symbol @code{IN_LIBRARY}.
 205 You may also want to build with @code{ENABLE_COSTLY_RELOCATABLE}, in which case
 206 you will also need to define @code{INSTALLDIR}.
 207 The following fragment can be added to an override @code{Makefile.am} used
 208 to build gnulib (@pxref{Modified build rules}).
 209
 210 @example
 211 AM_CPPFLAGS += -DIN_LIBRARY -DENABLE_COSTLY_RELOCATABLE
 212
 213 if SHLIBS_IN_BINDIR
 214 AM_CPPFLAGS += -DINSTALLDIR=\"$(bindir)\"
 215 else
 216 AM_CPPFLAGS += -DINSTALLDIR=\"$(libdir)\"
 217 endif
 218 @end example
 219
 220 @code{SHLIBS_IN_BINDIR} is defined in @file{configure.ac} as follows:
 221
 222 @smallexample
 223 AM_CONDITIONAL([SHLIBS_IN_BINDIR],
 224                [case "$host_os" in mingw* | cygwin*) true;; *) false;; esac])
 225 @end smallexample
 226
 227 @item
 228 You may also need to add a couple of variable assignments to your
 229 @file{configure.ac}.
 230
 231 If your package (or any package you rely on, e.g.@: gettext-runtime)
 232 will be relocated together with a set of installed shared libraries,
 233 then set @var{RELOCATABLE_LIBRARY_PATH} to a colon-separated list
 234 of those libraries' directories, e.g.
 235 @example
 236 RELOCATABLE_LIBRARY_PATH='$(libdir)'
 237 @end example
 238
 239 If your @file{config.h} is not in @file{$(top_builddir)}, then set
 240 @var{RELOCATABLE_CONFIG_H_DIR} to its directory, e.g.
 241 @example
 242 RELOCATABLE_CONFIG_H_DIR='$(top_builddir)/src'
 243 @end example
 244 @end enumerate