Re: The havelib module

[Bruno Haible]

Hi Sylvain,

Sylvain Beucler wrote:
> Can you explain me basically what it does and how to use it?
> (is it even meant for external use?)

I'm adding this doc to the gnulib manual. To view it reasonably:

  $ git pull
  $ cd doc
  $ make gnulib.info; info -f ./gnulib.info
  $ make gnulib.html; konqueror gnulib.html



2009-02-08  Bruno Haible  <address@hidden>

        Document the AC_LIB_LINKFLAGS macro.
        * doc/havelib.texi: New file, mostly written on 2005-05-24.
        * doc/gnulib.texi: Include it.

============================ doc/havelib.texi =============================
@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}, address@hidden)}

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}, address@hidden, 
address@hidden, address@hidden)}

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
@address@hidden/lib}, its include files are installed in
@address@hidden/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
@address@hidden 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 address@hidden 10203
  extern int address@hidden; /* initialized to address@hidden */
@end smallexample
@noindent
and use a test like
@smallexample
  AC_TRY_RUN([int main () @{ return address@hidden != address@hidden; @}])
@end smallexample
===========================================================================
--- doc/gnulib.texi.orig        2009-02-09 01:26:03.000000000 +0100
+++ doc/gnulib.texi     2009-02-09 00:28:32.000000000 +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
 
address@hidden havelib.texi
+
 @include relocatable-maint.texi
 
 @include func.texi