--- a/ChangeLog	Mon Feb 09 00:27:43 2009 +0100
+++ b/ChangeLog	Mon Feb 09 01:29:54 2009 +0100
@@ -1,3 +1,9 @@
+2009-02-08  Bruno Haible  <bruno@clisp.org>
+
+	Document the AC_LIB_LINKFLAGS macro.
+	* doc/havelib.texi: New file, mostly written on 2005-05-24.
+	* doc/gnulib.texi: Include it.
+
 2009-02-08  Bruno Haible  <bruno@clisp.org>
 
 	Fix wrong order of sections, compared to TOC.

--- a/doc/gnulib.texi	Mon Feb 09 00:27:43 2009 +0100
+++ b/doc/gnulib.texi	Mon Feb 09 01:29:54 2009 +0100
@@ -5819,6 +5819,7 @@
 * error and progname::
 * gcd::
 * Regular expressions::
+* Searching for Libraries::
 * Supporting Relocation::
 * func::
 * warnings::
@@ -5903,6 +5904,8 @@
 
 @include regexprops-generic.texi
 
+@include havelib.texi
+
 @include relocatable-maint.texi
 
 @include func.texi

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/havelib.texi	Mon Feb 09 01:29:54 2009 +0100
@@ -0,0 +1,167 @@
+@node Searching for Libraries
+@section Searching for Libraries
+
+The following macros check for the presence or location of certain C, C++, or
+Fortran library archive files.
+
+@unnumberedsubsec Simple Library Tests
+
+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}
+variable.
+
+@unnumberedsubsec Locating Libraries
+
+The following macros, defined in the Gnulib module @code{havelib}, search for
+the location of certain C, C++, or Fortran library archive files and make the
+found location available to the compilation process and to further Autoconf
+tests.
+
+@deffn Macro @code{AC_LIB_LINKFLAGS(@var{name}, [@var{dependencies}])}
+
+Searches for @code{lib<@var{name}>} and the libraries corresponding to
+explicit and implicit dependencies.  Sets and AC_SUBSTs 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.
+
+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}])}
+
+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
+@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
+@code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} to empty.
+@end deffn
+
+These macros assume that when a library is installed in
+@code{@var{some_directory}/lib}, its include files are installed in
+@code{@var{some_directory}/include}.
+
+The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS}
+deal with are the following:
+
+@itemize @bullet
+@item
+The library is not necessarily already in the search path (@code{CPPFLAGS} for
+the include file search path, @code{LDFLAGS} for the library search path).
+The macro provides a @samp{--with-lib<@var{name}>} option.  The user of the
+@samp{configure} script can use this option to indicate the location of the
+library and its include files.  If not provided, the @code{--prefix} directory
+is searched as well.
+
+@item
+The library is not necessarily already in the run time library search path.
+To avoid the need for setting an environment variable like
+@code{LD_LIBRARY_PATH}, the macro adds the appropriate run time search path
+options to the @code{LIB<@var{NAME}>} variable.  This works on most systems.
+It can also be inhibited: The user of @samp{configure} can use the
+@code{--disable-rpath} option to force an installation that doesn't contain
+hardcoded library search paths but instead may require the use of an
+environment variable like @code{LD_LIBRARY_PATH}.
+@end itemize
+
+The macros also set a variable @code{LTLIB<@var{NAME}>}, that should be used
+when linking with libtool.  Both @code{LTLIB<@var{NAME}>} and
+@code{LIB<@var{NAME}>} contain essentially the same option, but where
+@code{LIB<@var{NAME}>} contains platform dependent flags like
+@samp{-Wl,-rpath}, @code{LTLIB<@var{NAME}>} contains platform independent
+flags like @samp{-R}.
+
+@unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
+
+Suppose you want to use @code{libz}, the compression library.
+
+@enumerate
+@item
+In configure.ac you add the line
+
+@smallexample
+  AC_CONFIG_AUX_DIR([build-aux])
+  AC_LIB_LINKFLAGS([z])
+@end smallexample
+
+@noindent
+Note that since the @code{AC_LIB_LINKFLAGS} invocation modifies the CPPFLAGS,
+it should precede all tests that check for header files, declarations,
+structures or types.
+
+@item
+To the package's @file{build-aux} directory you add the file
+@file{config.rpath}, also part of the Gnulib @code{havelib} module.
+(@code{gnulib-tool} will usually do this for you automatically.)
+
+@item
+In @code{Makefile.in} you add @code{@@LIBZ@@} to the link command line of
+your program.  Or, if you are using Automake, you add @code{$(LIBZ)} to the
+@code{LDADD} variable that corresponds to your program.
+@end enumerate
+
+@unnumberedsubsubsec Dependencies
+
+The dependencies list is a space separated list of library names that
+@code{lib@var{name}} is known to depend upon.  Example: If @code{libfooy}
+depends on @code{libfoox}, and @code{libfooz} depends on @code{libfoox} and
+@code{libfooy}, you can write:
+
+@smallexample
+AC_LIB_LINKFLAGS([foox])
+AC_LIB_LINKFLAGS([fooy], [foox])
+AC_LIB_LINKFLAGS([fooz], [foox fooy])
+@end smallexample
+
+@noindent
+Explicit dependencies are necessary if you cannot assume that a @code{.la}
+file, created by libtool, is installed.  If you can assume that
+@code{libfooy.la} is installed by libtool (and has not been omitted by the
+ package distributor!), you can omit the explicit dependency and just write
+
+@smallexample
+AC_LIB_LINKFLAGS([fooy])
+@end smallexample
+
+@noindent
+This way, you don't need to know in advance which libraries the needed
+library depends upon.
+
+@unnumberedsubsubsec Static vs. shared
+
+The macros find the libraries regardless whether they are installed as
+shared or static libraries.
+
+@unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
+
+The macros determine the directories that should be added to the compiler
+preprocessor's search path and to the linker's search path.  For the
+compiler preprocessor, @code{-I} options with the necessary directories are
+added to the @code{CPPFLAGS} variable, for use by the whole package.  For
+the linker, appropriate options are added to the @code{LIB<@var{NAME}>} and
+@code{LTLIB<@var{NAME}>} variables, for use during linking by those programs
+and libraries that need the dependency on @code{lib<@var{name}>}.  You need
+to use the value of @code{LIB<@var{NAME}>} or @code{LTLIB<@var{NAME}>} in the
+Makefiles.  @code{LTLIB<@var{NAME}>} is for use with libtool, whereas
+@code{LIB<@var{NAME}>} is for when libtool is not involved in linking.
+
+The macros do not check whether the include files and the library found
+match.  If you want to verify this at configure time, one technique is
+to have a version number in the include files and a version number in the
+library, like this:
+@smallexample
+  #define LIB@var{NAME}_VERSION 10203
+  extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
+@end smallexample
+@noindent
+and use a test like
+@smallexample
+  AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
+@end smallexample