NEWS.stable: log cherry-pick [e446f25]->[c092018] relocatable-shell: Update suggested...

[gnulib.git] / doc / havelib.texi

diff --git a/doc/havelib.texi b/doc/havelib.texi
index 642ca9d..a776d52 100644 (file)
--- a/doc/havelib.texi
+++ b/doc/havelib.texi
@@ -8,9 +8,9 @@ Fortran library archive files.
 
 The macros @code{AC_CHECK_LIB}, @code{AC_SEARCH_LIBS} from GNU Autoconf check
 for the presence of certain C, C++, or Fortran library archive files.
-The libraries are looked up in the default linker path -- a system dependent
-list of directories, that usually contains the @file{/usr/lib} directory --
- and those directories given by @code{-L} options in the @code{LDFLAGS}
+The libraries are looked up in the default linker path---a system dependent
+list of directories, that usually contains the @file{/usr/lib} directory---and
+those directories given by @code{-L} options in the @code{LDFLAGS}
 variable.
 
 @unnumberedsubsec Locating Libraries
@@ -31,13 +31,14 @@ by @code{-I} options.
 This macro should be used when @code{lib<@var{name}>} is expected to be found.
 @end deffn
 
-@deffn Macro @code{AC_LIB_HAVE_LINKFLAGS(@var{name}, [@var{dependencies}], [@var{includes}], [@var{testcode}])}
+@deffn Macro @code{AC_LIB_HAVE_LINKFLAGS(@var{name}, [@var{dependencies}], [@var{includes}], [@var{testcode}], [@var{missing-message}])}
 
 Searches for @code{lib<@var{name}>} and the libraries corresponding to
 explicit and implicit dependencies, together with the specified include files
-and the ability to compile and link the specified @var{testcode}.  If found,
-it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=yes} and the
-@code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with
+and the ability to compile and link the specified @var{testcode}.  The
+@var{missing-message} defaults to @code{no} and may contain additional hints
+for the user.  If found, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=yes}
+and the @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with
 @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable
 by @code{-I} options, and #defines @code{HAVE_LIB<@var{NAME}>} to 1.
 Otherwise, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=no} and
@@ -165,3 +166,42 @@ and use a test like
 @smallexample
   AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
 @end smallexample
+
+@unnumberedsubsubsec Bi-arch systems
+
+A bi-arch system is one where
+@itemize
+@item
+the processor has a 32-bit execution mode and a 64-bit execution mode
+(for example, x86_64, ia64, sparc64, powerpc64), and
+@item
+32-bit mode libraries and executables and 64-bit mode libraries are both
+installed, and
+@item
+32-bit mode libraries and object files cannot be mixed with 64-bit mode
+ones.
+@end itemize
+
+On several types of such systems, for historical reasons, the 32-bit libraries
+are installed in @file{@var{prefix}/lib}, whereas the 64-bit libraries are
+installed in
+@itemize
+@item
+@file{@var{prefix}/lib64} on many glibc systems,
+@item
+@file{@var{prefix}/lib/64} on Solaris systems.
+@end itemize
+
+On such systems, in 64-bit mode, @command{configure} will search for the
+libraries in @file{@var{prefix}/lib64} or @file{@var{prefix}/lib/64},
+respectively, not in @file{@var{prefix}/lib}.  A user can adhere to these
+system-wide conventions by using the @samp{--libdir} option when installing
+packages.  When a user has already installed packages in 64-bit mode using
+the GNU default @samp{--libdir=@var{prefix}/lib}, he can make this directory
+adhere to the system-wide convention by placing a symbolic link:
+@table @asis
+@item On glibc systems:
+@code{ln -s lib @var{prefix}/lib64}
+@item On Solaris systems:
+@code{ln -s . @var{prefix}/lib/64}
+@end table