diff options
Diffstat (limited to 'doc/ltb2.texi')
-rw-r--r-- | doc/ltb2.texi | 167 |
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. + + + + |