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 @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
  83
  84 Suppose you want to use @code{libz}, the compression library.
  85
  86 @enumerate
  87 @item
  88 In configure.ac you add the line
  89
  90 @smallexample
  91   AC_CONFIG_AUX_DIR([build-aux])
  92   AC_LIB_LINKFLAGS([z])
  93 @end smallexample
  94
  95 @noindent
  96 Note that since the @code{AC_LIB_LINKFLAGS} invocation modifies the CPPFLAGS,
  97 it should precede all tests that check for header files, declarations,
  98 structures or types.
  99
 100 @item
 101 To the package's @file{build-aux} directory you add the file
 102 @file{config.rpath}, also part of the Gnulib @code{havelib} module.
 103 (@code{gnulib-tool} will usually do this for you automatically.)
 104
 105 @item
 106 In @code{Makefile.in} you add @code{@@LIBZ@@} to the link command line of
 107 your program.  Or, if you are using Automake, you add @code{$(LIBZ)} to the
 108 @code{LDADD} variable that corresponds to your program.
 109 @end enumerate
 110
 111 @unnumberedsubsubsec Dependencies
 112
 113 The dependencies list is a space separated list of library names that
 114 @code{lib@var{name}} is known to depend upon.  Example: If @code{libfooy}
 115 depends on @code{libfoox}, and @code{libfooz} depends on @code{libfoox} and
 116 @code{libfooy}, you can write:
 117
 118 @smallexample
 119 AC_LIB_LINKFLAGS([foox])
 120 AC_LIB_LINKFLAGS([fooy], [foox])
 121 AC_LIB_LINKFLAGS([fooz], [foox fooy])
 122 @end smallexample
 123
 124 @noindent
 125 Explicit dependencies are necessary if you cannot assume that a @code{.la}
 126 file, created by libtool, is installed.  If you can assume that
 127 @code{libfooy.la} is installed by libtool (and has not been omitted by the
 128  package distributor!), you can omit the explicit dependency and just write
 129
 130 @smallexample
 131 AC_LIB_LINKFLAGS([fooy])
 132 @end smallexample
 133
 134 @noindent
 135 This way, you don't need to know in advance which libraries the needed
 136 library depends upon.
 137
 138 @unnumberedsubsubsec Static vs. shared
 139
 140 The macros find the libraries regardless whether they are installed as
 141 shared or static libraries.
 142
 143 @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
 144
 145 The macros determine the directories that should be added to the compiler
 146 preprocessor's search path and to the linker's search path.  For the
 147 compiler preprocessor, @code{-I} options with the necessary directories are
 148 added to the @code{CPPFLAGS} variable, for use by the whole package.  For
 149 the linker, appropriate options are added to the @code{LIB<@var{NAME}>} and
 150 @code{LTLIB<@var{NAME}>} variables, for use during linking by those programs
 151 and libraries that need the dependency on @code{lib<@var{name}>}.  You need
 152 to use the value of @code{LIB<@var{NAME}>} or @code{LTLIB<@var{NAME}>} in the
 153 Makefiles.  @code{LTLIB<@var{NAME}>} is for use with libtool, whereas
 154 @code{LIB<@var{NAME}>} is for when libtool is not involved in linking.
 155
 156 The macros do not check whether the include files and the library found
 157 match.  If you want to verify this at configure time, one technique is
 158 to have a version number in the include files and a version number in the
 159 library, like this:
 160 @smallexample
 161   #define LIB@var{NAME}_VERSION 10203
 162   extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
 163 @end smallexample
 164 @noindent
 165 and use a test like
 166 @smallexample
 167   AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
 168 @end smallexample
 169
 170 @unnumberedsubsubsec Bi-arch systems
 171
 172 A bi-arch system is one where
 173 @itemize
 174 @item
 175 the processor has a 32-bit execution mode and a 64-bit execution mode
 176 (for example, x86_64, ia64, sparc64, powerpc64), and
 177 @item
 178 32-bit mode libraries and executables and 64-bit mode libraries are both
 179 installed, and
 180 @item
 181 32-bit mode libraries and object files cannot be mixed with 64-bit mode
 182 ones.
 183 @end itemize
 184
 185 On several types of such systems, for historical reasons, the 32-bit libraries
 186 are installed in @file{@var{prefix}/lib}, whereas the 64-bit libraries are
 187 installed in
 188 @itemize
 189 @item
 190 @file{@var{prefix}/lib64} on many glibc systems,
 191 @item
 192 @file{@var{prefix}/lib/64} on Solaris systems.
 193 @end itemize
 194
 195 On such systems, in 64-bit mode, @command{configure} will search for the
 196 libraries in @file{@var{prefix}/lib64} or @file{@var{prefix}/lib/64},
 197 respectively, not in @file{@var{prefix}/lib}.  A user can adhere to these
 198 system-wide conventions by using the @samp{--libdir} option when installing
 199 packages.  When a user has already installed packages in 64-bit mode using
 200 the GNU default @samp{--libdir=@var{prefix}/lib}, he can make this directory
 201 adhere to the system-wide convention by placing a symbolic link:
 202 @table @asis
 203 @item On glibc systems:
 204 @code{ln -s lib @var{prefix}/lib64}
 205 @item On Solaris systems:
 206 @code{ln -s . @var{prefix}/lib/64}
 207 @end table