1 files changed, 167 insertions, 0 deletions
diff --git a/doc/ltb2.texi b/doc/ltb2.texi
new file mode 100644
index 0000000..ade5b41
--- /dev/null
+++ b/doc/ltb2.texi
@@ -0,0 +1,167 @@
+@unnumbered Synopsis
+
+Let a project consist of two installable libraries and a binary
+(@file{ltb2}) linked to both of them.  One of the libraries depends on
+an external library, which has a libtool archive installed along with
+the shared library.  The figure below illustrates this scheme:
+
+@example
+@group
+  ltb2  <---+-- liba <==== @file{@var{libdir}}/libdep.la
+            |
+            +-- libb
+@end group
+@end example
+
+Then, for GNU/Linux systems the wrapper script would issue the relink
+command that ends with the following options (split along multiple
+lines for readability):
+
+@example
+-Wl,-rpath -Wl,@var{srcdir}/liba/.libs
+-Wl,-rpath -Wl,@var{libdir}
+-Wl,-rpath -Wl,@var{srcdir}/libb/.libs
+-Wl,-rpath -Wl,@var{libdir}
+@end example
+
+For FreeBSD, the @env{LD_LIBRARY_PATH} used by the wrapper will look
+like:
+
+@example
+@var{srcdir}/liba/.libs:@var{libdir}:@var{srcdir}/libb/.libs:$LD_LIBRARY_PATH
+@end example
+
+In both cases, the @file{@var{libdir}} directory appearing before
+@file{libb} will cause the @file{libb} library to be searched in 
+@file{@var{libdir}} first.  If a prior version of the project is
+installed in the same prefix as the @file{libdep} library, then the
+@command{ltb2} wrapper will use the version of @file{liba} from the
+local source tree, but the version of @file{libb} installed on the
+system.
+
+@unnumbered Background
+
+The issue was initially discovered when building @uref{https://mailutils.org,GNU
+mailutils} on FreeBSD with support for OpenLDAP enabled.  The latter
+incurred dependency on @file{libldap}, which was installed (along with
+@file{libldap.la}) in @file{/usr/local/lib}.
+
+The package built in these conditions failed most tests because it was
+using mailutils libraries from prior version, installed in
+@file{/usr/local/lib}.
+
+The issue has been confirmed to exist on GNU/Linux as well
+(@pxref{affected systems}).
+
+@unnumbered The test case
+
+A minimal testcase is available for download from
+@uref{ltbug-2.tar.gz}.  It consists of two subpackages:
+@file{ltb2dep} implementing the dependency library, and the main
+test package @file{ltb2}.  The latter builds and installs two libraries:
+@file{liba} and @file{libb}, and a test program @command{ltb2}, linked
+with both of these.  The @file{liba} library provides the function
+@samp{ltb2a_version}.  The @file{libb} library implements a similar
+function @samp{ltb2b_version}.  Both functions print on the standard
+output the value of the @samp{LTBUG_ID} macro defined at the compile
+time.  The @command{ltb2} program calls both functions in order.
+
+The test script first builds and installs the dependency library
+@file{ltb2dep}.  Then, it builds the package with
+@code{LTBUG_ID="installed"} and installs it.  When run, the installed
+@command{ltb2} program will output
+
+@example
+ltb2a: installed
+ltb2b: installed
+@end example
+
+Finally, the test rebuilds the package with @code{LTBUG_ID="local"}
+and runs the @command{ltb2} program from the source tree.  The program
+then outputs:
+
+@example
+ltb2a: local
+ltb2b: installed
+@end example
+
+@noindent
+This shows that the command uses @file{libltb2a} from the local source
+tree and @file{libltb2b} previously installed on the system.
+
+Follow these steps to run the test:
+
+@enumerate 1
+@item Unpack the archive
+
+@example
+tar xf ltbug-2.tar.gz
+@end example
+
+@item Run
+
+@example
+sh ltbug-2/test.sh
+@end example
+
+@noindent
+or
+
+@example
+make -C ltbug-2 check
+@end example
+
+@end enumerate
+
+If the bug is present, you will see the following output:
+
+@example
+Building dependency library
+Building and installing project
+Building local copy of the project
+Running test program
+Test failed:
+--- expout      2019-12-12 13:45:53.193782824 +0200
++++ stdout      2019-12-12 13:45:53.222782826 +0200
+@@ -1,2 +1,2 @@
+ ltb2a: local
+-ltb2b: local
++ltb2b: installed
+Keeping the directories in place.  When no longer needed, run:
+rm -rf /tmp/ltb-test2
+rm -rf ltb-test2
+make: *** [check] Error 1
+@end example
+
+The directory @file{ltb-test2} will be left on disk for examination.
+It will contain:
+
+@table @file
+@item build_dep
+Build directory for the dependency library @file{libltb2dep}.
+
+@item build_inst
+A directory where the installed version of the package was built.
+
+@item build_local
+Local build directory.  The test runs @command{build_local/src/ltb2}.
+
+@item expout
+Expected standard output.
+
+@item stdout
+Obtained standard output.
+
+@item ltb2.out
+Standard output generated by the build process.
+
+@item ltb2.err
+Standard output generated by the build process.
+@end table
+
+The test script takes the same command line options as described above
+for the @file{ltb1} test.
+
+
+
+