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 --
13 and 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}])}
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.
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}.
51 The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS}
52 deal with are the following:
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
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}.
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
81 @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS}
83 Suppose you want to use @code{libz}, the compression library.
87 In configure.ac you add the line
90 AC_CONFIG_AUX_DIR([build-aux])
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,
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.)
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.
110 @unnumberedsubsubsec Dependencies
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:
118 AC_LIB_LINKFLAGS([foox])
119 AC_LIB_LINKFLAGS([fooy], [foox])
120 AC_LIB_LINKFLAGS([fooz], [foox fooy])
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
130 AC_LIB_LINKFLAGS([fooy])
134 This way, you don't need to know in advance which libraries the needed
135 library depends upon.
137 @unnumberedsubsubsec Static vs. shared
139 The macros find the libraries regardless whether they are installed as
140 shared or static libraries.
142 @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS}
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.
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
160 #define LIB@var{NAME}_VERSION 10203
161 extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */
166 AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}])
169 @unnumberedsubsubsec Bi-arch systems
171 A bi-arch system is one where
174 the processor has a 32-bit execution mode and a 64-bit execution mode
175 (for example, x86_64, ia64, sparc64, powerpc64), and
177 32-bit mode libraries and executables and 64-bit mode libraries are both
180 32-bit mode libraries and object files cannot be mixed with 64-bit mode
184 On several types of such systems, for historical reasons, the 32-bit libraries
185 are installed in @file{@var{prefix}/lib}, whereas the 64-bit libraries are
189 @file{@var{prefix}/lib64} on many glibc systems,
191 @file{@var{prefix}/lib/64} on Solaris systems.
194 On such systems, in 64-bit mode, @command{configure} will search for the
195 libraries in @file{@var{prefix}/lib64} or @file{@var{prefix}/lib/64},
196 respectively, not in @file{@var{prefix}/lib}. A user can adhere to these
197 system-wide conventions by using the @samp{--libdir} option when installing
198 packages. When a user has already installed packages in 64-bit mode using
199 the GNU default @samp{--libdir=@var{prefix}/lib}, he can make this directory
200 adhere to the system-wide convention by placing a symbolic link:
202 @item On glibc systems:
203 @code{ln -s lib @var{prefix}/lib64}
204 @item On Solaris systems:
205 @code{ln -s . @var{prefix}/lib/64}