autoconf: Generic Functions

1 
1 5.5.3 Generic Function Checks
1 -----------------------------
1 
1 These macros are used to find functions not covered by the "particular"
1 test macros.  If the functions might be in libraries other than the
1 default C library, first call `AC_CHECK_LIB' for those libraries.  If
1 you need to check the behavior of a function as well as find out
11 whether it is present, you have to write your own test for it (⇒
 Writing Tests).
1 
1  -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND],
1           [ACTION-IF-NOT-FOUND])
1      If C function FUNCTION is available, run shell commands
1      ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND.  If you just want
1      to define a symbol if the function is available, consider using
1      `AC_CHECK_FUNCS' instead.  This macro checks for functions with C
1      linkage even when `AC_LANG(C++)' has been called, since C is more
1      standardized than C++.  (⇒Language Choice, for more
1      information about selecting the language for checks.)
1 
1      This macro caches its result in the `ac_cv_func_FUNCTION' variable.
1 
1  -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND],
1           [ACTION-IF-NOT-FOUND])
1      For each FUNCTION enumerated in the blank-or-newline-separated
1      argument list, define `HAVE_FUNCTION' (in all capitals) if it is
1      available.  If ACTION-IF-FOUND is given, it is additional shell
1      code to execute when one of the functions is found.  You can give
1      it a value of `break' to break out of the loop on the first match.
1      If ACTION-IF-NOT-FOUND is given, it is executed when one of the
1      functions is not found.
1 
1      Results are cached for each FUNCTION as in `AC_CHECK_FUNC'.
1 
1  -- Macro: AC_CHECK_FUNCS_ONCE (FUNCTION...)
1      For each FUNCTION enumerated in the blank-or-newline-separated
1      argument list, define `HAVE_FUNCTION' (in all capitals) if it is
1      available.  This is a once-only variant of `AC_CHECK_FUNCS'.  It
1      generates the checking code at most once, so that `configure' is
1      smaller and faster; but the checks cannot be conditionalized and
1      are always done once, early during the `configure' run.
1 
1 
1    Autoconf follows a philosophy that was formed over the years by those
1 who have struggled for portability: isolate the portability issues in
1 specific files, and then program as if you were in a Posix environment.
1 Some functions may be missing or unfixable, and your package must be
1 ready to replace them.
1 
1    Suitable replacements for many such problem functions are available
1 from Gnulib (⇒Gnulib).
1 
1  -- Macro: AC_LIBOBJ (FUNCTION)
1      Specify that `FUNCTION.c' must be included in the executables to
1      replace a missing or broken implementation of FUNCTION.
1 
1      Technically, it adds `FUNCTION.$ac_objext' to the output variable
1      `LIBOBJS' if it is not already in, and calls `AC_LIBSOURCE' for
1      `FUNCTION.c'.  You should not directly change `LIBOBJS', since
1      this is not traceable.
1 
1  -- Macro: AC_LIBSOURCE (FILE)
1      Specify that FILE might be needed to compile the project.  If you
1      need to know what files might be needed by a `configure.ac', you
1      should trace `AC_LIBSOURCE'.  FILE must be a literal.
1 
1      This macro is called automatically from `AC_LIBOBJ', but you must
1      call it explicitly if you pass a shell variable to `AC_LIBOBJ'.  In
1      that case, since shell variables cannot be traced statically, you
1      must pass to `AC_LIBSOURCE' any possible files that the shell
1      variable might cause `AC_LIBOBJ' to need.  For example, if you
1      want to pass a variable `$foo_or_bar' to `AC_LIBOBJ' that holds
1      either `"foo"' or `"bar"', you should do:
1 
1           AC_LIBSOURCE([foo.c])
1           AC_LIBSOURCE([bar.c])
1           AC_LIBOBJ([$foo_or_bar])
1 
1      There is usually a way to avoid this, however, and you are
1      encouraged to simply call `AC_LIBOBJ' with literal arguments.
1 
1      Note that this macro replaces the obsolete `AC_LIBOBJ_DECL', with
1      slightly different semantics: the old macro took the function name,
1      e.g., `foo', as its argument rather than the file name.
1 
1  -- Macro: AC_LIBSOURCES (FILES)
1      Like `AC_LIBSOURCE', but accepts one or more FILES in a
1      comma-separated M4 list.  Thus, the above example might be
1      rewritten:
1 
1           AC_LIBSOURCES([foo.c, bar.c])
1           AC_LIBOBJ([$foo_or_bar])
1 
1  -- Macro: AC_CONFIG_LIBOBJ_DIR (DIRECTORY)
1      Specify that `AC_LIBOBJ' replacement files are to be found in
1      DIRECTORY, a name relative to the top level of the source tree.
1      The replacement directory defaults to `.', the top level
1      directory, and the most typical value is `lib', corresponding to
1      `AC_CONFIG_LIBOBJ_DIR([lib])'.
1 
1      `configure' might need to know the replacement directory for the
1      following reasons: (i) some checks use the replacement files, (ii)
1      some macros bypass broken system headers by installing links to the
1      replacement headers (iii) when used in conjunction with Automake,
1      within each makefile, DIRECTORY is used as a relative path from
1      `$(top_srcdir)' to each object named in `LIBOBJS' and `LTLIBOBJS',
1      etc.
1 
1 
1    It is common to merely check for the existence of a function, and ask
1 for its `AC_LIBOBJ' replacement if missing.  The following macro is a
1 convenient shorthand.
1 
1  -- Macro: AC_REPLACE_FUNCS (FUNCTION...)
1      Like `AC_CHECK_FUNCS', but uses `AC_LIBOBJ(FUNCTION)' as
1      ACTION-IF-NOT-FOUND.  You can declare your replacement function by
1      enclosing the prototype in `#ifndef HAVE_FUNCTION'.  If the system
1      has the function, it probably declares it in a header file you
1      should be including, so you shouldn't redeclare it lest your
1      declaration conflict.
1