| @node Searching for Libraries |
| @section Searching for Libraries |
| |
| The following macros check for the presence or location of certain C, C++, or |
| Fortran library archive files. |
| |
| @unnumberedsubsec Simple Library Tests |
| |
| The macros @code{AC_CHECK_LIB}, @code{AC_SEARCH_LIBS} from GNU Autoconf check |
| for the presence of certain C, C++, or Fortran library archive files. |
| The libraries are looked up in the default linker path---a system dependent |
| list of directories, that usually contains the @file{/usr/lib} directory---and |
| those directories given by @code{-L} options in the @code{LDFLAGS} |
| variable. |
| |
| @unnumberedsubsec Locating Libraries |
| |
| The following macros, defined in the Gnulib module @code{havelib}, search for |
| the location of certain C, C++, or Fortran library archive files and make the |
| found location available to the compilation process and to further Autoconf |
| tests. |
| |
| @deffn Macro @code{AC_LIB_LINKFLAGS(@var{name}, [@var{dependencies}])} |
| |
| Searches for @code{lib<@var{name}>} and the libraries corresponding to |
| explicit and implicit dependencies. Sets and AC_SUBSTs the |
| @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with |
| @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable |
| by @code{-I} options. |
| |
| This macro should be used when @code{lib<@var{name}>} is expected to be found. |
| @end deffn |
| |
| @deffn Macro @code{AC_LIB_HAVE_LINKFLAGS(@var{name}, [@var{dependencies}], [@var{includes}], [@var{testcode}], [@var{missing-message}])} |
| |
| Searches for @code{lib<@var{name}>} and the libraries corresponding to |
| explicit and implicit dependencies, together with the specified include files |
| and the ability to compile and link the specified @var{testcode}. The |
| @var{missing-message} defaults to @code{no} and may contain additional hints |
| for the user. If found, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=yes} |
| and the @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} variables (with |
| @code{<@var{NAME}>} in upper case) and augments the @code{CPPFLAGS} variable |
| by @code{-I} options, and #defines @code{HAVE_LIB<@var{NAME}>} to 1. |
| Otherwise, it sets and AC_SUBSTs @code{HAVE_LIB<@var{NAME}>=no} and |
| @code{LIB<@var{NAME}>} and @code{LTLIB<@var{NAME}>} to empty. |
| @end deffn |
| |
| These macros assume that when a library is installed in |
| @code{@var{some_directory}/lib}, its include files are installed in |
| @code{@var{some_directory}/include}. |
| |
| The complexities that @code{AC_LIB_LINKFLAGS} and @code{AC_LIB_HAVE_LINKFLAGS} |
| deal with are the following: |
| |
| @itemize @bullet |
| @item |
| The library is not necessarily already in the search path (@code{CPPFLAGS} for |
| the include file search path, @code{LDFLAGS} for the library search path). |
| The macro provides a @samp{--with-lib<@var{name}>} option. The user of the |
| @samp{configure} script can use this option to indicate the location of the |
| library and its include files. If not provided, the @code{--prefix} directory |
| is searched as well. |
| |
| @item |
| The library is not necessarily already in the run time library search path. |
| To avoid the need for setting an environment variable like |
| @code{LD_LIBRARY_PATH}, the macro adds the appropriate run time search path |
| options to the @code{LIB<@var{NAME}>} variable. This works on most systems. |
| It can also be inhibited: The user of @samp{configure} can use the |
| @code{--disable-rpath} option to force an installation that doesn't contain |
| hardcoded library search paths but instead may require the use of an |
| environment variable like @code{LD_LIBRARY_PATH}. |
| @end itemize |
| |
| The macros also set a variable @code{LTLIB<@var{NAME}>}, that should be used |
| when linking with libtool. Both @code{LTLIB<@var{NAME}>} and |
| @code{LIB<@var{NAME}>} contain essentially the same option, but where |
| @code{LIB<@var{NAME}>} contains platform dependent flags like |
| @samp{-Wl,-rpath}, @code{LTLIB<@var{NAME}>} contains platform independent |
| flags like @samp{-R}. |
| |
| @unnumberedsubsubsec Example of using @code{AC_LIB_LINKFLAGS} |
| |
| Suppose you want to use @code{libz}, the compression library. |
| |
| @enumerate |
| @item |
| In configure.ac you add the line |
| |
| @smallexample |
| AC_CONFIG_AUX_DIR([build-aux]) |
| AC_LIB_LINKFLAGS([z]) |
| @end smallexample |
| |
| @noindent |
| Note that since the @code{AC_LIB_LINKFLAGS} invocation modifies the CPPFLAGS, |
| it should precede all tests that check for header files, declarations, |
| structures or types. |
| |
| @item |
| To the package's @file{build-aux} directory you add the file |
| @file{config.rpath}, also part of the Gnulib @code{havelib} module. |
| (@code{gnulib-tool} will usually do this for you automatically.) |
| |
| @item |
| In @code{Makefile.in} you add @code{@@LIBZ@@} to the link command line of |
| your program. Or, if you are using Automake, you add @code{$(LIBZ)} to the |
| @code{LDADD} variable that corresponds to your program. |
| @end enumerate |
| |
| @unnumberedsubsubsec Dependencies |
| |
| The dependencies list is a space separated list of library names that |
| @code{lib@var{name}} is known to depend upon. Example: If @code{libfooy} |
| depends on @code{libfoox}, and @code{libfooz} depends on @code{libfoox} and |
| @code{libfooy}, you can write: |
| |
| @smallexample |
| AC_LIB_LINKFLAGS([foox]) |
| AC_LIB_LINKFLAGS([fooy], [foox]) |
| AC_LIB_LINKFLAGS([fooz], [foox fooy]) |
| @end smallexample |
| |
| @noindent |
| Explicit dependencies are necessary if you cannot assume that a @code{.la} |
| file, created by libtool, is installed. If you can assume that |
| @code{libfooy.la} is installed by libtool (and has not been omitted by the |
| package distributor!), you can omit the explicit dependency and just write |
| |
| @smallexample |
| AC_LIB_LINKFLAGS([fooy]) |
| @end smallexample |
| |
| @noindent |
| This way, you don't need to know in advance which libraries the needed |
| library depends upon. |
| |
| @unnumberedsubsubsec Static vs. shared |
| |
| The macros find the libraries regardless whether they are installed as |
| shared or static libraries. |
| |
| @unnumberedsubsubsec @code{CPPFLAGS} vs. @code{LDFLAGS} |
| |
| The macros determine the directories that should be added to the compiler |
| preprocessor's search path and to the linker's search path. For the |
| compiler preprocessor, @code{-I} options with the necessary directories are |
| added to the @code{CPPFLAGS} variable, for use by the whole package. For |
| the linker, appropriate options are added to the @code{LIB<@var{NAME}>} and |
| @code{LTLIB<@var{NAME}>} variables, for use during linking by those programs |
| and libraries that need the dependency on @code{lib<@var{name}>}. You need |
| to use the value of @code{LIB<@var{NAME}>} or @code{LTLIB<@var{NAME}>} in the |
| Makefiles. @code{LTLIB<@var{NAME}>} is for use with libtool, whereas |
| @code{LIB<@var{NAME}>} is for when libtool is not involved in linking. |
| |
| The macros do not check whether the include files and the library found |
| match. If you want to verify this at configure time, one technique is |
| to have a version number in the include files and a version number in the |
| library, like this: |
| @smallexample |
| #define LIB@var{NAME}_VERSION 10203 |
| extern int lib@var{name}_version; /* initialized to LIB@var{NAME}_VERSION */ |
| @end smallexample |
| @noindent |
| and use a test like |
| @smallexample |
| AC_TRY_RUN([int main () @{ return lib@var{name}_version != LIB@var{NAME}_VERSION; @}]) |
| @end smallexample |
| |
| @unnumberedsubsubsec Bi-arch systems |
| |
| A bi-arch system is one where |
| @itemize |
| @item |
| the processor has a 32-bit execution mode and a 64-bit execution mode |
| (for example, x86_64, ia64, sparc64, powerpc64), and |
| @item |
| 32-bit mode libraries and executables and 64-bit mode libraries are both |
| installed, and |
| @item |
| 32-bit mode libraries and object files cannot be mixed with 64-bit mode |
| ones. |
| @end itemize |
| |
| On several types of such systems, for historical reasons, the 32-bit libraries |
| are installed in @file{@var{prefix}/lib}, whereas the 64-bit libraries are |
| installed in |
| @itemize |
| @item |
| @file{@var{prefix}/lib64} on many glibc systems, |
| @item |
| @file{@var{prefix}/lib/64} on Solaris systems. |
| @end itemize |
| |
| On such systems, in 64-bit mode, @command{configure} will search for the |
| libraries in @file{@var{prefix}/lib64} or @file{@var{prefix}/lib/64}, |
| respectively, not in @file{@var{prefix}/lib}. A user can adhere to these |
| system-wide conventions by using the @samp{--libdir} option when installing |
| packages. When a user has already installed packages in 64-bit mode using |
| the GNU default @samp{--libdir=@var{prefix}/lib}, he can make this directory |
| adhere to the system-wide convention by placing a symbolic link: |
| @table @asis |
| @item On glibc systems: |
| @code{ln -s lib @var{prefix}/lib64} |
| @item On Solaris systems: |
| @code{ln -s . @var{prefix}/lib/64} |
| @end table |