1 @node Searching for Libraries
2 @section Searching for Libraries
4 The following macros check for the presence or location of certain C, C++, or
5 Fortran library archive files.
7 @unnumberedsubsec Simple Library Tests
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}
16 @unnumberedsubsec Locating Libraries
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
23 @deffn Macro @code{AC_LIB_LINKFLAGS(@var{name}, [@var{dependencies}])}
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
31 This macro should be used when @code{lib<@var{name}>} is expected to be found.
34 @deffn Macro @code{AC_LIB_HAVE_LINKFLAGS(@var{name}, [@var{dependencies}], [@var{includes}], [@var{testcode}], [@var{missing-message}])}
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.
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}.
52 The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS}
53 deal with are the following:
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
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}.
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
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!
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.
93 @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
95 Suppose you want to use @code{libz}, the compression library.
99 In configure.ac you add the line
102 AC_CONFIG_AUX_DIR([build-aux])
103 AC_LIB_LINKFLAGS([z])
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,
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.)
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.
122 @unnumberedsubsubsec Dependencies
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:
130 AC_LIB_LINKFLAGS([foox])
131 AC_LIB_LINKFLAGS([fooy], [foox])
132 AC_LIB_LINKFLAGS([fooz], [foox fooy])
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
142 AC_LIB_LINKFLAGS([fooy])
146 This way, you don't need to know in advance which libraries the needed
147 library depends upon.
149 @unnumberedsubsubsec Static vs. shared
151 The macros find the libraries regardless whether they are installed as
152 shared or static libraries.
154 @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
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.
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
172 #define LIB@var{NAME}_VERSION 10203
173 extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
178 AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
181 @unnumberedsubsubsec Bi-arch systems
183 A bi-arch system is one where
186 the processor has a 32-bit execution mode and a 64-bit execution mode
187 (for example, x86_64, ia64, sparc64, powerpc64), and
189 32-bit mode libraries and executables and 64-bit mode libraries are both
192 32-bit mode libraries and object files cannot be mixed with 64-bit mode
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
201 @file{@var{prefix}/lib64} on many glibc systems,
203 @file{@var{prefix}/lib/64} on Solaris systems.
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:
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}