Searching for Libraries
=======================

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

Simple Library Tests
--------------------

The macros AC_CHECK_LIB, 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 /usr/lib directory -- and those directories given by -L options in the LDFLAGS variable.

Locating Libraries
------------------

The following macros, defined in the Gnulib module 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.

 -- Macro: AC_LIB_LINKFLAGS(NAME, [DEPENDENCIES])

     Searches for lib<NAME> and the libraries corresponding to explicit and implicit dependencies.  Sets and AC_SUBSTs the LIB<NAME> and LTLIB<NAME> variables (with <NAME> in upper case) and augments the CPPFLAGS variable by -I options.

     This macro should be used when lib<NAME> is expected to be found.

 -- Macro: AC_LIB_HAVE_LINKFLAGS(NAME, [DEPENDENCIES], [INCLUDES], [TESTCODE])

     Searches for lib<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 TESTCODE.  If found, it sets and AC_SUBSTs HAVE_LIB<NAME>=yes and the LIB<NAME> and LTLIB<NAME> variables (with <NAME> in upper case) and augments the CPPFLAGS variable by -I options, and #defines HAVE_LIB<NAME> to 1. Otherwise, it sets and AC_SUBSTs HAVE_LIB<NAME>=no and LIB<NAME> and LTLIB<NAME> to empty.

These macros assume that when a library is installed in SOME_DIRECTORY/lib, its include files are installed in SOME_DIRECTORY/include.

The complexities that AC_LIB_LINKFLAGS and AC_LIB_HAVE_LINKFLAGS deal with are the following:

  * The library is not necessarily already in the search path (CPPFLAGS for the include file search path, LDFLAGS for the library search path). The macro provides a --with-lib<NAME> option.  The user of the configure script can use this option to indicate the location of the library and its include files.  If not provided, the --prefix directory is searched as well.

  * The library is not necessarily already in the run time library search path. To avoid the need for setting an environment variable like LD_LIBRARY_PATH, the macro adds the appropriate run time search path options to the LIB<NAME> variable.  This works on most systems. It can also be inhibited: The user of configure can use the --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 LD_LIBRARY_PATH.

The macros also set a variable LTLIB<NAME>, that should be used when linking with libtool.  Both LTLIB<NAME> and LIB<NAME> contain essentially the same option, but where LIB<NAME> contains platform dependent flags like -Wl,-rpath, LTLIB<NAME> contains platform independent flags like -R.

Example of using AC_LIB_LINKFLAGS
.................................

Suppose you want to use libz, the compression library.

 1. In configure.ac you add the line

            AC_CONFIG_AUX_DIR([build-aux])
            AC_LIB_LINKFLAGS([z])

     Note that since the AC_LIB_LINKFLAGS invocation modifies the CPPFLAGS, it should precede all tests that check for header files, declarations, structures or types.

 2. To the package's build-aux directory you add the file config.rpath, also part of the Gnulib havelib module. (gnulib-tool will usually do this for you automatically.)

 3. In Makefile.in you add @LIBZ@ to the link command line of your program.  Or, if you are using Automake, you add $(LIBZ) to the LDADD variable that corresponds to your program.

Dependencies
............

The dependencies list is a space separated list of library names that libNAME is known to depend upon.  Example: If libfooy depends on libfoox, and libfooz depends on libfoox and libfooy, you can write:

     AC_LIB_LINKFLAGS([foox])
     AC_LIB_LINKFLAGS([fooy], [foox])
     AC_LIB_LINKFLAGS([fooz], [foox fooy])

Explicit dependencies are necessary if you cannot assume that a .la file, created by libtool, is installed.  If you can assume that libfooy.la is installed by libtool (and has not been omitted by the package distributor!), you can omit the explicit dependency and just write

     AC_LIB_LINKFLAGS([fooy])

This way, you don't need to know in advance which libraries the needed library depends upon.

Static vs. shared
.................

The macros find the libraries regardless whether they are installed as shared or static libraries.

CPPFLAGS vs. 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, -I options with the necessary directories are added to the CPPFLAGS variable, for use by the whole package.  For the linker, appropriate options are added to the LIB<NAME> and LTLIB<NAME> variables, for use during linking by those programs and libraries that need the dependency on lib<NAME>.  You need to use the value of LIB<NAME> or LTLIB<NAME> in the Makefiles.  LTLIB<NAME> is for use with libtool, whereas LIB<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:

       #define LIBNAME_VERSION 10203
       extern int libNAME_version; /* initialized to LIBNAME_VERSION */

and use a test like

       AC_TRY_RUN([int main () { return libNAME_version != LIBNAME_VERSION; }])

Bi-arch systems
...............

A bi-arch system is one where

  * the processor has a 32-bit execution mode and a 64-bit execution mode (for example, x86_64, ia64, sparc64, powerpc64), and

  * 32-bit mode libraries and executables and 64-bit mode libraries are both installed, and

  * 32-bit mode libraries and object files cannot be mixed with 64-bit mode ones.

On several types of such systems, for historical reasons, the 32-bit libraries are installed in PREFIX/lib, whereas the 64-bit libraries are installed in

  * PREFIX/lib64 on many glibc systems,

  * PREFIX/lib/64 on Solaris systems.

On such systems, in 64-bit mode, configure will search for the libraries in PREFIX/lib64 or PREFIX/lib/64, respectively, not in PREFIX/lib.  A user can adhere to these system-wide conventions by using the --libdir option when installing packages.  When a user has already installed packages in 64-bit mode using the GNU default --libdir=PREFIX/lib, he can make this directory adhere to the system-wide convention by placing a symbolic link:

On glibc systems:
     ln -s lib PREFIX/lib64

On Solaris systems:
     ln -s . PREFIX/lib/64