relocatable-lib{,-lgpl}: improve documentation

* doc/relocatable-maint.texi: Document use of relocatable-lib{,-lgpl}.
Various other updates.

2 files changed, 21 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index 95b4401861..bac0c1acf5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2017-07-26  Reuben Thomas  <rrt@sc3d.org>
+
+	relocatable-lib{,-lgpl}: improve documentation
+	* doc/relocatable-maint.texi: Document use of relocatable-lib{,-lgpl}.
+	Various other updates.
+
 2017-07-30  Reuben Thomas  <rrt@sc3d.org>
             Bruno Haible  <bruno@clisp.org>
 
diff --git a/doc/relocatable-maint.texi b/doc/relocatable-maint.texi
index 50b446bcff..edb4d26789 100644
--- a/doc/relocatable-maint.texi
+++ b/doc/relocatable-maint.texi
@@ -44,10 +44,6 @@ On other Unix systems, it installs a wrapper executable.  The wrapper
 sets the environment variable that controls shared library searching
 (usually @env{LD_LIBRARY_PATH}) and then invokes the real executable.
 
-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.
-
 @item
 On Windows, the executable's own directory is searched for libraries,
 so installing shared libraries into the executable's directory is
@@ -58,7 +54,8 @@ You can make your program relocatable by following these steps:
 
 @enumerate
 @item
-Import the @code{relocatable-prog} module.
+Import the @code{relocatable-prog} module.  For libraries, use the
+@code{relocatable-lib} or @code{relocatable-lib-lgpl} module.
 
 @item
 In every program, add to @code{main} as the first statement (even
@@ -71,6 +68,10 @@ set_program_name (argv[0]);
 The prototype for this function is in @file{progname.h}.
 
 @item
+If you want your code to be portable to platforms that do not support
+automatic initialization, call @code{set_relocation_prefix}.
+
+@item
 Everywhere where you use a constant pathname from installation-time,
 wrap it in @code{relocate} so it gets translated to the run-time situation.
 Example:
@@ -168,6 +169,7 @@ if ("@@RELOCATABLE@@" eq "yes") @{
 @}
 
 # Get some relocated directory names.
+# (The gnulib module 'configmake' can help with this.)
 $sysconfdir = relocate("@@sysconfdir@@");
 $some_datadir = relocate(@@datadir@@/something");
 @end example
@@ -188,6 +190,14 @@ foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
 endif
 @end example
 
+Also in @file{Makefile.am}, for each library @code{libfoo}, you add:
+
+@example
+libfoo_la_CPPFLAGS = -DIN_LIBRARY
+@end example
+
+(Adjust the suffix @code{la} as necessary if you are not using libtool.)
+
 @item
 You may also need to add a couple of variable assignments to your
 @file{configure.ac}.