8.3.5 Library Files

The following macros check for the presence of certain C, C++, Fortran, or Go library archive files.

Macro: AC_CHECK_LIB (library, function, [action-if-found], [action-if-not-found], [other-libraries])

Test whether the library library is available by trying to link a test program that calls function function with the library. function should be a function provided by the library. Use the base name of the library; e.g., to check for -lmp, use ‘mp’ as the library argument.

action-if-found is a list of shell commands to run if the link with the library succeeds; action-if-not-found is a list of shell commands to run if the link fails. If action-if-found is not specified, the default action prepends -llibrary to LIBS and defines ‘HAVE_LIBlibrary’ (in all capitals). This macro is intended to support building LIBS in a right-to-left (least-dependent to most-dependent) fashion such that library dependencies are satisfied as a natural side effect of consecutive tests. Linkers are sensitive to library ordering so the order in which LIBS is generated is important to reliable detection of libraries.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g., -lXt -lX11. Otherwise, this macro may fail to detect that library is present, because linking the test program can fail with unresolved symbols. The other-libraries argument should be limited to cases where it is desirable to test for one library in the presence of another that is not already in LIBS.

AC_CHECK_LIB requires some care in usage, and should be avoided in some common cases. Many standard functions like gethostbyname appear in the standard C library on some hosts, and in special libraries like nsl on other hosts. On some hosts the special libraries contain variant implementations that you may not want to use. These days it is normally better to use AC_SEARCH_LIBS([gethostbyname], [nsl]) instead of AC_CHECK_LIB([nsl], [gethostbyname]).

The result of this test is cached in the ac_cv_lib_library_function variable.

Macro: AC_SEARCH_LIBS (function, search-libs, [action-if-found], [action-if-not-found], [other-libraries])

Search for a library defining function if it’s not already available. This equates to calling ‘AC_LINK_IFELSE([AC_LANG_CALL([], [function])])’ first with no libraries, then for each library listed in search-libs.

Prepend -llibrary to LIBS for the first library found to contain function, and run action-if-found. If the function is not found, run action-if-not-found.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g., -lXt -lX11. Otherwise, this macro fails to detect that function is present, because linking the test program always fails with unresolved symbols.

The result of this test is cached in the ac_cv_search_function variable as ‘none required’ if function is already available, as ‘no’ if no library containing function was found, otherwise as the -llibrary option that needs to be prepended to LIBS.