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---and
  13 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}], [@var{missing-message}])}
  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}.  The
  39 @var{missing-message} defaults to @code{no} and may contain additional hints
  40 for the user.  If found, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=yes}
  41 and the @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with
  42 @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable
  43 by @code{-I} options, and #defines @code{HAVE_LIB<@var{NAME}>} to 1.
  44 Otherwise, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=no} and
  45 @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} to empty.
  46 @end deffn
  47
  48 These macros assume that when a library is installed in
  49 @code{@var{some_directory}/lib}, its include files are installed in
  50 @code{@var{some_directory}/include}.
  51
  52 The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS}
  53 deal with are the following:
  54
  55 @itemize @bullet
  56 @item
  57 The library is not necessarily already in the search path (@code{CPPFLAGS} for
  58 the include file search path, @code{LDFLAGS} for the library search path).
  59 The macro provides a @samp{--with-lib<@var{name}>} option.  The user of the
  60 @samp{configure} script can use this option to indicate the location of the
  61 library and its include files.  If not provided, the @code{--prefix} directory
  62 is searched as well.
  63
  64 @item
  65 The library is not necessarily already in the run time library search path.
  66 To avoid the need for setting an environment variable like
  67 @code{LD_LIBRARY_PATH}, the macro adds the appropriate run time search path
  68 options to the @code{LIB<@var{NAME}>} variable.  This works on most systems.
  69 It can also be inhibited: The user of @samp{configure} can use the
  70 @code{--disable-rpath} option to force an installation that doesn't contain
  71 hardcoded library search paths but instead may require the use of an
  72 environment variable like @code{LD_LIBRARY_PATH}.
  73 @end itemize
  74
  75 The macros also set a variable @code{LTLIB<@var{NAME}>}, that should be used
  76 when linking with libtool.  Both @code{LTLIB<@var{NAME}>} and
  77 @code{LIB<@var{NAME}>} contain essentially the same option, but where
  78 @code{LIB<@var{NAME}>} contains platform dependent flags like
  79 @samp{-Wl,-rpath}, @code{LTLIB<@var{NAME}>} contains platform independent
  80 flags like @samp{-R}.
  81
  82 If you, by mistake, use @code{LIB<@var{NAME}>} instead of
  83 @code{LTLIB<@var{NAME}>} when linking with libtool, you will observe that the
  84 binaries created in the build dir will prefer the shared libraries in the
  85 installation directories over the shared libraries in the build dir; this can
  86 lead to all sorts of build failures, test failures, or crashes!
  87
  88 If you, on the other hand, by mistake, use @code{LTLIB<@var{NAME}>} instead of
  89 @code{LIB<@var{NAME}>} when linking @emph{without} libtool, you will observe
  90 build failures, because the @samp{-R} options contained in
  91 @code{LTLIB<@var{NAME}>} are not valid options to compilers such as GCC.
  92
  93 @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
  94
  95 Suppose you want to use @code{libz}, the compression library.
  96
  97 @enumerate
  98 @item
  99 In configure.ac you add the line
 100
 101 @smallexample
 102   AC_CONFIG_AUX_DIR([build-aux])
 103   AC_LIB_LINKFLAGS([z])
 104 @end smallexample
 105
 106 @noindent
 107 Note that since the @code{AC_LIB_LINKFLAGS} invocation modifies the CPPFLAGS,
 108 it should precede all tests that check for header files, declarations,
 109 structures or types.
 110
 111 @item
 112 To the package's @file{build-aux} directory you add the file
 113 @file{config.rpath}, also part of the Gnulib @code{havelib} module.
 114 (@code{gnulib-tool} will usually do this for you automatically.)
 115
 116 @item
 117 In @code{Makefile.in} you add @code{@@LIBZ@@} to the link command line of
 118 your program.  Or, if you are using Automake, you add @code{$(LIBZ)} to the
 119 @code{LDADD} variable that corresponds to your program.
 120 @end enumerate
 121
 122 @unnumberedsubsubsec Dependencies
 123
 124 The dependencies list is a space separated list of library names that
 125 @code{lib@var{name}} is known to depend upon.  Example: If @code{libfooy}
 126 depends on @code{libfoox}, and @code{libfooz} depends on @code{libfoox} and
 127 @code{libfooy}, you can write:
 128
 129 @smallexample
 130 AC_LIB_LINKFLAGS([foox])
 131 AC_LIB_LINKFLAGS([fooy], [foox])
 132 AC_LIB_LINKFLAGS([fooz], [foox fooy])
 133 @end smallexample
 134
 135 @noindent
 136 Explicit dependencies are necessary if you cannot assume that a @code{.la}
 137 file, created by libtool, is installed.  If you can assume that
 138 @code{libfooy.la} is installed by libtool (and has not been omitted by the
 139  package distributor!), you can omit the explicit dependency and just write
 140
 141 @smallexample
 142 AC_LIB_LINKFLAGS([fooy])
 143 @end smallexample
 144
 145 @noindent
 146 This way, you don't need to know in advance which libraries the needed
 147 library depends upon.
 148
 149 @unnumberedsubsubsec Static vs. shared
 150
 151 The macros find the libraries regardless whether they are installed as
 152 shared or static libraries.
 153
 154 @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
 155
 156 The macros determine the directories that should be added to the compiler
 157 preprocessor's search path and to the linker's search path.  For the
 158 compiler preprocessor, @code{-I} options with the necessary directories are
 159 added to the @code{CPPFLAGS} variable, for use by the whole package.  For
 160 the linker, appropriate options are added to the @code{LIB<@var{NAME}>} and
 161 @code{LTLIB<@var{NAME}>} variables, for use during linking by those programs
 162 and libraries that need the dependency on @code{lib<@var{name}>}.  You need
 163 to use the value of @code{LIB<@var{NAME}>} or @code{LTLIB<@var{NAME}>} in the
 164 Makefiles.  @code{LTLIB<@var{NAME}>} is for use with libtool, whereas
 165 @code{LIB<@var{NAME}>} is for when libtool is not involved in linking.
 166
 167 The macros do not check whether the include files and the library found
 168 match.  If you want to verify this at configure time, one technique is
 169 to have a version number in the include files and a version number in the
 170 library, like this:
 171 @smallexample
 172   #define LIB@var{NAME}_VERSION 10203
 173   extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
 174 @end smallexample
 175 @noindent
 176 and use a test like
 177 @smallexample
 178   AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
 179 @end smallexample
 180
 181 @unnumberedsubsubsec Bi-arch systems
 182
 183 A bi-arch system is one where
 184 @itemize
 185 @item
 186 the processor has a 32-bit execution mode and a 64-bit execution mode
 187 (for example, x86_64, ia64, sparc64, powerpc64), and
 188 @item
 189 32-bit mode libraries and executables and 64-bit mode libraries are both
 190 installed, and
 191 @item
 192 32-bit mode libraries and object files cannot be mixed with 64-bit mode
 193 ones.
 194 @end itemize
 195
 196 On several types of such systems, for historical reasons, the 32-bit libraries
 197 are installed in @file{@var{prefix}/lib}, whereas the 64-bit libraries are
 198 installed in
 199 @itemize
 200 @item
 201 @file{@var{prefix}/lib64} on many glibc systems,
 202 @item
 203 @file{@var{prefix}/lib/64} on Solaris systems.
 204 @end itemize
 205
 206 On such systems, in 64-bit mode, @command{configure} will search for the
 207 libraries in @file{@var{prefix}/lib64} or @file{@var{prefix}/lib/64},
 208 respectively, not in @file{@var{prefix}/lib}.  A user can adhere to these
 209 system-wide conventions by using the @samp{--libdir} option when installing
 210 packages.  When a user has already installed packages in 64-bit mode using
 211 the GNU default @samp{--libdir=@var{prefix}/lib}, he can make this directory
 212 adhere to the system-wide convention by placing a symbolic link:
 213 @table @asis
 214 @item On glibc systems:
 215 @code{ln -s lib @var{prefix}/lib64}
 216 @item On Solaris systems:
 217 @code{ln -s . @var{prefix}/lib/64}
 218 @end table