From cfabb63265a6319684bba91e62242e29bcf0e2d7 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Mon, 9 Feb 2009 01:29:54 +0100 Subject: [PATCH] Document the 'havelib' module. --- ChangeLog | 6 ++ doc/gnulib.texi | 3 + doc/havelib.texi | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 176 insertions(+) create mode 100644 doc/havelib.texi diff --git a/ChangeLog b/ChangeLog index a8ff289e3..1241e6adf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2009-02-08 Bruno Haible + 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 + Fix wrong order of sections, compared to TOC. * doc/gnulib.texi: Include relocatable-maint.texi after the "Regular expressions" node, not before. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 2122122f9..d9383f6a9 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5819,6 +5819,7 @@ This list of functions is sorted according to the header that declares them. * error and progname:: * gcd:: * Regular expressions:: +* Searching for Libraries:: * Supporting Relocation:: * func:: * warnings:: @@ -5903,6 +5904,8 @@ generated automatically. @include regexprops-generic.texi +@include havelib.texi + @include relocatable-maint.texi @include func.texi diff --git a/doc/havelib.texi b/doc/havelib.texi new file mode 100644 index 000000000..642ca9d12 --- /dev/null +++ b/doc/havelib.texi @@ -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 -- 2.11.0