File: autoconf.info,  Node: Libraries,  Next: Library Functions,  Prev: Files,  Up: Existing Tests

5.4 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’.