doc/havelib.texi

   1 @node Searching for Libraries
   2 @section Searching for Libraries
   3
   4 The following macros check for the presence or location of certain C, C++, or
   5 Fortran library archive files.
   6
   7 @unnumberedsubsec Simple Library Tests
   8
   9 The macros @code{AC_CHECK_LIB}, @code{AC_SEARCH_LIBS} from GNU Autoconf check
  10 for the presence of certain C, C++, or Fortran library archive files.
  11 The libraries are looked up in the default linker path -- a system dependent
  12 list of directories, that usually contains the @file{/usr/lib} directory --
  13  and those directories given by @code{-L} options in the @code{LDFLAGS}
  14 variable.
  15
  16 @unnumberedsubsec Locating Libraries
  17
  18 The following macros, defined in the Gnulib module @code{havelib}, search for
  19 the location of certain C, C++, or Fortran library archive files and make the
  20 found location available to the compilation process and to further Autoconf
  21 tests.
  22
  23 @deffn Macro @code{AC_LIB_LINKFLAGS(@var{name}, [@var{dependencies}])}
  24
  25 Searches for @code{lib<@var{name}>} and the libraries corresponding to
  26 explicit and implicit dependencies.  Sets and AC_SUBSTs the
  27 @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with
  28 @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable
  29 by @code{-I} options.
  30
  31 This macro should be used when @code{lib<@var{name}>} is expected to be found.
  32 @end deffn
  33
  34 @deffn Macro @code{AC_LIB_HAVE_LINKFLAGS(@var{name}, [@var{dependencies}], [@var{includes}], [@var{testcode}])}
  35
  36 Searches for @code{lib<@var{name}>} and the libraries corresponding to
  37 explicit and implicit dependencies, together with the specified include files
  38 and the ability to compile and link the specified @var{testcode}.  If found,
  39 it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=yes} and the
  40 @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with
  41 @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable
  42 by @code{-I} options, and #defines @code{HAVE_LIB<@var{NAME}>} to 1.
  43 Otherwise, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=no} and
  44 @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} to empty.
  45 @end deffn
  46
  47 These macros assume that when a library is installed in
  48 @code{@var{some_directory}/lib}, its include files are installed in
  49 @code{@var{some_directory}/include}.
  50
  51 The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS}
  52 deal with are the following:
  53
  54 @itemize @bullet
  55 @item
  56 The library is not necessarily already in the search path (@code{CPPFLAGS} for
  57 the include file search path, @code{LDFLAGS} for the library search path).
  58 The macro provides a @samp{--with-lib<@var{name}>} option.  The user of the
  59 @samp{configure} script can use this option to indicate the location of the
  60 library and its include files.  If not provided, the @code{--prefix} directory
  61 is searched as well.
  62
  63 @item
  64 The library is not necessarily already in the run time library search path.
  65 To avoid the need for setting an environment variable like
  66 @code{LD_LIBRARY_PATH}, the macro adds the appropriate run time search path
  67 options to the @code{LIB<@var{NAME}>} variable.  This works on most systems.
  68 It can also be inhibited: The user of @samp{configure} can use the
  69 @code{--disable-rpath} option to force an installation that doesn't contain
  70 hardcoded library search paths but instead may require the use of an
  71 environment variable like @code{LD_LIBRARY_PATH}.
  72 @end itemize
  73
  74 The macros also set a variable @code{LTLIB<@var{NAME}>}, that should be used
  75 when linking with libtool.  Both @code{LTLIB<@var{NAME}>} and
  76 @code{LIB<@var{NAME}>} contain essentially the same option, but where
  77 @code{LIB<@var{NAME}>} contains platform dependent flags like
  78 @samp{-Wl,-rpath}, @code{LTLIB<@var{NAME}>} contains platform independent
  79 flags like @samp{-R}.
  80
  81 @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
  82
  83 Suppose you want to use @code{libz}, the compression library.
  84
  85 @enumerate
  86 @item
  87 In configure.ac you add the line
  88
  89 @smallexample
  90   AC_CONFIG_AUX_DIR([build-aux])
  91   AC_LIB_LINKFLAGS([z])
  92 @end smallexample
  93
  94 @noindent
  95 Note that since the @code{AC_LIB_LINKFLAGS} invocation modifies the CPPFLAGS,
  96 it should precede all tests that check for header files, declarations,
  97 structures or types.
  98
  99 @item
 100 To the package's @file{build-aux} directory you add the file
 101 @file{config.rpath}, also part of the Gnulib @code{havelib} module.
 102 (@code{gnulib-tool} will usually do this for you automatically.)
 103
 104 @item
 105 In @code{Makefile.in} you add @code{@@LIBZ@@} to the link command line of
 106 your program.  Or, if you are using Automake, you add @code{$(LIBZ)} to the
 107 @code{LDADD} variable that corresponds to your program.
 108 @end enumerate
 109
 110 @unnumberedsubsubsec Dependencies
 111
 112 The dependencies list is a space separated list of library names that
 113 @code{lib@var{name}} is known to depend upon.  Example: If @code{libfooy}
 114 depends on @code{libfoox}, and @code{libfooz} depends on @code{libfoox} and
 115 @code{libfooy}, you can write:
 116
 117 @smallexample
 118 AC_LIB_LINKFLAGS([foox])
 119 AC_LIB_LINKFLAGS([fooy], [foox])
 120 AC_LIB_LINKFLAGS([fooz], [foox fooy])
 121 @end smallexample
 122
 123 @noindent
 124 Explicit dependencies are necessary if you cannot assume that a @code{.la}
 125 file, created by libtool, is installed.  If you can assume that
 126 @code{libfooy.la} is installed by libtool (and has not been omitted by the
 127  package distributor!), you can omit the explicit dependency and just write
 128
 129 @smallexample
 130 AC_LIB_LINKFLAGS([fooy])
 131 @end smallexample
 132
 133 @noindent
 134 This way, you don't need to know in advance which libraries the needed
 135 library depends upon.
 136
 137 @unnumberedsubsubsec Static vs. shared
 138
 139 The macros find the libraries regardless whether they are installed as
 140 shared or static libraries.
 141
 142 @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
 143
 144 The macros determine the directories that should be added to the compiler
 145 preprocessor's search path and to the linker's search path.  For the
 146 compiler preprocessor, @code{-I} options with the necessary directories are
 147 added to the @code{CPPFLAGS} variable, for use by the whole package.  For
 148 the linker, appropriate options are added to the @code{LIB<@var{NAME}>} and
 149 @code{LTLIB<@var{NAME}>} variables, for use during linking by those programs
 150 and libraries that need the dependency on @code{lib<@var{name}>}.  You need
 151 to use the value of @code{LIB<@var{NAME}>} or @code{LTLIB<@var{NAME}>} in the
 152 Makefiles.  @code{LTLIB<@var{NAME}>} is for use with libtool, whereas
 153 @code{LIB<@var{NAME}>} is for when libtool is not involved in linking.
 154
 155 The macros do not check whether the include files and the library found
 156 match.  If you want to verify this at configure time, one technique is
 157 to have a version number in the include files and a version number in the
 158 library, like this:
 159 @smallexample
 160   #define LIB@var{NAME}_VERSION 10203
 161   extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
 162 @end smallexample
 163 @noindent
 164 and use a test like
 165 @smallexample
 166   AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
 167 @end smallexample