Merge commit 'a39d4083cab589d7cd6a13e8a4b8db8875261d75'

[gnulib.git] / doc / relocatable-maint.texi

diff --git a/doc/relocatable-maint.texi b/doc/relocatable-maint.texi
index da57402..8780b84 100644 (file)
--- a/doc/relocatable-maint.texi
+++ b/doc/relocatable-maint.texi
@@ -8,29 +8,29 @@ and have it work correctly (including i18n).  So many users need to go
 through @code{configure; make; make install} with all its
 dependencies, options, and hurdles.
 
 through @code{configure; make; make install} with all its
 dependencies, options, and hurdles.
 

-Red Hat, Debian, and similar package systems solve the ``ease of
+Red Hat, Debian, and other binary distributions solve the ``ease of

 installation'' problem, but they hardwire path names, usually to
 @file{/usr} or @file{/usr/local}.  This means that users need root
 privileges to install a binary package, and prevents installing two
 different versions of the same binary package.
 
 A relocatable program can be moved or copied to a different location
 installation'' problem, but they hardwire path names, usually to
 @file{/usr} or @file{/usr/local}.  This means that users need root
 privileges to install a binary package, and prevents installing two
 different versions of the same binary package.
 
 A relocatable program can be moved or copied to a different location

-on the filesystem.  It is possible to make symlinks to the installed
+on the file system.  It is possible to make symlinks to the installed

 and moved programs, and invoke them through the symlink. It is
 possible to do the same thing with a hard link @emph{only} if the hard
 link file is in the same directory as the real program.
 
 and moved programs, and invoke them through the symlink. It is
 possible to do the same thing with a hard link @emph{only} if the hard
 link file is in the same directory as the real program.
 

-The @code{relocatable} module aims to ease the process of making a GNU
-program relocatable.  It helps overcome two obstacles.  First, it aids
+The @code{relocatable-prog} module aims to ease the process of making a
+GNU program relocatable.  It helps overcome two obstacles.  First, it aids

 with relocating the hard-coded references to absolute file names that
 GNU programs often contain.  These references must be fixed up at
 runtime if a program is to be successfully relocated.  The
 with relocating the hard-coded references to absolute file names that
 GNU programs often contain.  These references must be fixed up at
 runtime if a program is to be successfully relocated.  The

-@code{relocatable} module provides a function @code{relocate} that
+@code{relocatable-prog} module provides a function @code{relocate} that

 does this job.
 
 Second, the loader must be able to find shared libraries linked to
 relocatable executables or referenced by other shared libraries linked
 does this job.
 
 Second, the loader must be able to find shared libraries linked to
 relocatable executables or referenced by other shared libraries linked

-to relocatable executables.  The @code{relocatable} module helps out
+to relocatable executables.  The @code{relocatable-prog} module helps out

 here in a platform-specific way:
 
 @itemize
 here in a platform-specific way:
 
 @itemize


@@ -46,7 +46,7 @@ sets the environment variable that controls shared library searching
 
 This approach does not always work.  On OpenBSD and OpenServer,
 prereleases of Libtool 1.5 put absolute file names of libraries in
 
 This approach does not always work.  On OpenBSD and OpenServer,
 prereleases of Libtool 1.5 put absolute file names of libraries in

-executables, which prevents searching any other locations. 
+executables, which prevents searching any other locations.

 
 @item
 On Windows, the executable's own directory is searched for libraries,
 
 @item
 On Windows, the executable's own directory is searched for libraries,


@@ -58,7 +58,7 @@ You can make your program relocatable by following these steps:
 
 @enumerate
 @item
 
 @enumerate
 @item

-Import the @code{relocatable} module.
+Import the @code{relocatable-prog} module.

 
 @item
 In every program, add to @code{main} as the first statement (even
 
 @item
 In every program, add to @code{main} as the first statement (even


@@ -82,13 +82,34 @@ bindtextdomain (PACKAGE, LOCALEDIR);
 @noindent
 becomes:
 
 @noindent
 becomes:
 

-@example 
+@example

 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
 @end example
 
 The prototype for this function is in @file{relocatable.h}.
 
 @item
 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
 @end example
 
 The prototype for this function is in @file{relocatable.h}.
 
 @item

+The @code{set_program_name} function can also configure some
+additional libraries to relocate files that they access, by defining
+corresponding C preprocessor symbols to 1.  The libraries for which
+this is supported and the corresponding preprocessor symbols are:
+
+@table @asis
+@item libcharset
+@code{DEPENDS_ON_LIBCHARSET}
+
+@item libiconv
+@code{DEPENDS_ON_LIBICONV}
+
+@item libintl
+@code{DEPENDS_ON_LIBINTL}
+@end table
+
+Defining the symbol for a library makes every program in the package
+depend on that library, whether the program really uses the library or
+not, so this feature should be used with some caution.
+
+@item

 If your package installs shell scripts, also import the
 @code{relocatable-script} module.  Then, near the beginning of each
 shell script that your package installs, add the following:
 If your package installs shell scripts, also import the
 @code{relocatable-script} module.  Then, near the beginning of each
 shell script that your package installs, add the following:


@@ -102,8 +123,10 @@ if test "@@RELOCATABLE@@" = yes; then
   func_find_curr_installdir # determine curr_installdir
   func_find_prefixes
   # Relocate the directory variables that we use.
   func_find_curr_installdir # determine curr_installdir
   func_find_prefixes
   # Relocate the directory variables that we use.

-  gettext_dir=`echo "$gettext_dir/" | sed -e 
-"s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" | sed -e 's,/$,,'`
+  gettext_dir=`
+    echo "$gettext_dir/" \
+    | sed -e "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" \
+    | sed -e 's,/$,,'`

 fi
 @end example
 
 fi
 @end example
 


@@ -123,8 +146,8 @@ endif
 @end example
 
 @item
 @end example
 
 @item

-You may also need to add one or two variable assignments to your
-@file{configure.ac}.  
+You may also need to add a couple of variable assignments to your
+@file{configure.ac}.

 
 If your package (or any package you rely on, e.g.@: gettext-runtime)
 will be relocated together with a set of installed shared libraries,
 
 If your package (or any package you rely on, e.g.@: gettext-runtime)
 will be relocated together with a set of installed shared libraries,