path: root/util/autoconf/autoconf.info-3

This is Info file autoconf.info, produced by Makeinfo-1.55 from the
input file ./autoconf.texi.

START-INFO-DIR-ENTRY
* Autoconf: (autoconf).         Create source code configuration scripts.
END-INFO-DIR-ENTRY

   This file documents the GNU Autoconf package for creating scripts to
configure source code packages using templates and an `m4' macro
package.

   Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: autoconf.info,  Node: Run Time,  Next: Portable Shell,  Prev: Examining Libraries,  Up: Writing Tests

Checking Run Time Behavior
==========================

   Sometimes you need to find out how a system performs at run time,
such as whether a given function has a certain capability or bug.  If
you can, make such checks when your program runs instead of when it is
configured.  You can check for things like the machine's endianness when
your program initializes itself.

   If you really need to test for a run-time behavior while configuring,
you can write a test program to determine the result, and compile and
run it using `AC_TRY_RUN'.  Avoid running test programs if possible,
because using them prevents people from configuring your package for
cross-compiling.

* Menu:

* Test Programs::               Running test programs.
* Guidelines::			General rules for writing test programs.
* Test Functions::		Avoiding pitfalls in test programs.


File: autoconf.info,  Node: Test Programs,  Next: Guidelines,  Up: Run Time

Running Test Programs
---------------------

   Use the following macro if you need to test run-time behavior of the
system while configuring.

 - Macro: AC_TRY_RUN (PROGRAM, ACTION-IF-TRUE [, ACTION-IF-FALSE [,
          ACTION-IF-CROSS-COMPILING]])
     PROGRAM is the text of a C program, on which shell variable and
     backquote substitutions are performed.  If it compiles and links
     successfully and returns an exit status of 0 when executed, run
     shell commands ACTION-IF-TRUE.  Otherwise run shell commands
     ACTION-IF-FALSE; the exit status of the program is available in
     the shell variable `$?'.  This macro uses `CFLAGS' or `CXXFLAGS',
     `CPPFLAGS', `LDFLAGS', and `LIBS' when compiling.

     If the C compiler being used does not produce executables that run
     on the system where `configure' is being run, then the test
     program is not run.  If the optional shell commands
     ACTION-IF-CROSS-COMPILING are given, they are run instead and this
     macro calls `AC_C_CROSS' if it has not already been called.
     Otherwise, `configure' prints an error message and exits.

   Try to provide a pessimistic default value to use when
cross-compiling makes run-time tests impossible.  You do this by
passing the optional last argument to `AC_TRY_RUN'.  `autoconf' prints
a warning message when creating `configure' each time it encounters a
call to `AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given.
You may ignore the warning, though users will not be able to configure
your package for cross-compiling.  A few of the macros distributed with
Autoconf produce this warning message.

   To configure for cross-compiling you can also choose a value for
those parameters based on the canonical system name (*note Manual
Configuration::.).  Alternatively, set up a test results cache file with
the correct values for the target system (*note Caching Results::.).

   To provide a default for calls of `AC_TRY_RUN' that are embedded in
other macros, including a few of the ones that come with Autoconf, you
can call `AC_C_CROSS' before running them.  Then, if the shell variable
`cross_compiling' is set to `yes', use an alternate method to get the
results instead of calling the macros.

 - Macro: AC_C_CROSS
     If the C compiler being used does not produce executables that can
     run on the system where `configure' is being run, set the shell
     variable `cross_compiling' to `yes', otherwise `no'.


File: autoconf.info,  Node: Guidelines,  Next: Test Functions,  Prev: Test Programs,  Up: Run Time

Guidelines for Test Programs
----------------------------

   Test programs should not write anything to the standard output.  They
should return 0 if the test succeeds, nonzero otherwise, so that success
can be distinguished easily from a core dump or other failure;
segmentation violations and other failures produce a nonzero exit
status.  Test programs should `exit', not `return', from `main',
because on some systems (old Suns, at least) the argument to `return'
in `main' is ignored.

   Test programs can use `#if' or `#ifdef' to check the values of
preprocessor macros defined by tests that have already run.  For
example, if you call `AC_HEADER_STDC', then later on in `configure.in'
you can have a test program that includes an ANSI C header file
conditionally:

     #if STDC_HEADERS
     # include <stdlib.h>
     #endif

   If a test program needs to use or create a data file, give it a name
that starts with `conftest', such as `conftestdata'.  The `configure'
script cleans up by running `rm -rf conftest*' after running test
programs and if the script is interrupted.


File: autoconf.info,  Node: Test Functions,  Prev: Guidelines,  Up: Run Time

Test Functions
--------------

   Function declarations in test programs should have a prototype
conditionalized for C++.  In practice, though, test programs rarely need
functions that take arguments.

     #ifdef __cplusplus
     foo(int i)
     #else
     foo(i) int i;
     #endif

   Functions that test programs declare should also be conditionalized
for C++, which requires `extern "C"' prototypes.  Make sure to not
include any header files containing clashing prototypes.

     #ifdef __cplusplus
     extern "C" void *malloc(size_t);
     #else
     char *malloc();
     #endif

   If a test program calls a function with invalid parameters (just to
see whether it exists), organize the program to ensure that it never
invokes that function.  You can do this by calling it in another
function that is never invoked.  You can't do it by putting it after a
call to `exit', because GCC version 2 knows that `exit' never returns
and optimizes out any code that follows it in the same block.

   If you include any header files, make sure to call the functions
relevant to them with the correct number of arguments, even if they are
just 0, to avoid compilation errors due to prototypes.  GCC version 2
has internal prototypes for several functions that it automatically
inlines; for example, `memcpy'.  To avoid errors when checking for
them, either pass them the correct number of arguments or redeclare them
with a different return type (such as `char').


File: autoconf.info,  Node: Portable Shell,  Next: Testing Values and Files,  Prev: Run Time,  Up: Writing Tests

Portable Shell Programming
==========================

   When writing your own checks, there are some shell script programming
techniques you should avoid in order to make your code portable.  The
Bourne shell and upward-compatible shells like Bash and the Korn shell
have evolved over the years, but to prevent trouble, do not take
advantage of features that were added after UNIX version 7, circa 1977.
You should not use shell functions, aliases, negated character classes,
or other features that are not found in all Bourne-compatible shells;
restrict yourself to the lowest common denominator.  Even `unset' is
not supported by all shells!

   The set of external programs you should run in a `configure' script
is fairly small.  *Note Utilities in Makefiles:
(standards.info)Utilities in Makefiles, for the list.  This restriction
allows users to start out with a fairly small set of programs and build
the rest, avoiding too many interdependencies between packages.

   Some of these external utilities have a portable subset of features,
as well; for example, don't rely on `ln' having a `-f' option or `cat'
having any options.  `sed' scripts should not contain comments or use
branch labels longer than 8 characters.  Don't use `grep -s' to
suppress output, because `grep -s' on System V does not suppress
output, only error messages.  Instead, redirect the standard output and
standard error (in case the file doesn't exist) of `grep' to
`/dev/null'.  Check the exit status of `grep' to determine whether it
found a match.


File: autoconf.info,  Node: Testing Values and Files,  Next: Multiple Cases,  Prev: Portable Shell,  Up: Writing Tests

Testing Values and Files
========================

   `configure' scripts need to test properties of many files and
strings.  Here are some portability problems to watch out for when doing
those tests.

   The `test' program is the way to perform many file and string tests.
It is often invoked by the alternate name `[', but using that name in
Autoconf code is asking for trouble since it is an `m4' quote character.

   If you need to make multiple checks using `test', combine them with
the shell operators `&&' and `||' instead of using the `test' operators
`-a' and `-o'.  On System V, the precedence of `-a' and `-o' is wrong
relative to the unary operators; consequently, POSIX does not specify
them, so using them is nonportable.  If you combine `&&' and `||' in
the same statement, keep in mind that they have equal precedence.

   To enable `configure' scripts to support cross-compilation, they
shouldn't do anything that tests features of the host system instead of
the target system.  But occasionally you may find it necessary to check
whether some arbitrary file exists.  To do so, use `test -f' or `test
-r'.  Do not use `test -x', because 4.3BSD does not have it.

   Another nonportable shell programming construction is
     VAR=${VAR:-VALUE}

The intent is to set VAR to VALUE only if it is not already set, but if
VAR has any value, even the empty string, to leave it alone.  Old BSD
shells, including the Ultrix `sh', don't accept the colon, and complain
and die.  A portable equivalent is
     : ${VAR=VALUE}


File: autoconf.info,  Node: Multiple Cases,  Next: Language Choice,  Prev: Testing Values and Files,  Up: Writing Tests

Multiple Cases
==============

   Some operations are accomplished in several possible ways, depending
on the UNIX variant.  Checking for them essentially requires a "case
statement".  Autoconf does not directly provide one; however, it is
easy to simulate by using a shell variable to keep track of whether a
way to perform the operation has been found yet.

   Here is an example that uses the shell variable `fstype' to keep
track of whether the remaining cases need to be checked.

     AC_MSG_CHECKING(how to get filesystem type)
     fstype=no
     # The order of these tests is important.
     AC_TRY_CPP([#include <sys/statvfs.h>
     #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4)
     if test $fstype = no; then
     AC_TRY_CPP([#include <sys/statfs.h>
     #include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3)
     fi
     if test $fstype = no; then
     AC_TRY_CPP([#include <sys/statfs.h>
     #include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX)
     fi
     # (more cases omitted here)
     AC_MSG_RESULT($fstype)


File: autoconf.info,  Node: Language Choice,  Prev: Multiple Cases,  Up: Writing Tests

Language Choice
===============

   Packages that use both C and C++ need to test features of both
compilers.  Autoconf-generated `configure' scripts check for C features
by default.  The following macros determine which language's compiler
is used in tests that follow in `configure.in'.

 - Macro: AC_LANG_C
     Do compilation tests using `CC' and `CPP' and use extension `.c'
     for test programs.

 - Macro: AC_LANG_CPLUSPLUS
     Do compilation tests using `CXX' and `CXXCPP' and use extension
     `.C' for test programs.

 - Macro: AC_LANG_SAVE
     Remember the current language (as set by `AC_LANG_C' or
     `AC_LANG_CPLUSPLUS') on a stack.  Does not change which language is
     current.  Use this macro and `AC_LANG_RESTORE' in macros that need
     to temporarily switch to a particular language.

 - Macro: AC_LANG_RESTORE
     Select the language that is saved on the top of the stack, as set
     by `AC_LANG_SAVE', and remove it from the stack.  This macro is
     equivalent to either `AC_LANG_C' or `AC_LANG_CPLUSPLUS', whichever
     had been run most recently when `AC_LANG_SAVE' was last called.

     Do not call this macro more times than `AC_LANG_SAVE'.

 - Macro: AC_REQUIRE_CPP
     Ensure that whichever preprocessor would currently be used for
     tests has been found.  Calls `AC_REQUIRE' (*note Prerequisite
     Macros::.) with an argument of either `AC_PROG_CPP' or
     `AC_PROG_CXXCPP', depending on which language is current.


File: autoconf.info,  Node: Results,  Next: Writing Macros,  Prev: Writing Tests,  Up: Top

Results of Tests
****************

   Once `configure' has determined whether a feature exists, what can
it do to record that information?  There are four sorts of things it can
do: define a C preprocessor symbol, set a variable in the output files,
save the result in a cache file for future `configure' runs, and print
a message letting the user know the result of the test.

* Menu:

* Defining Symbols::            Defining C preprocessor symbols.
* Setting Output Variables::	Replacing variables in output files.
* Caching Results::             Speeding up subsequent `configure' runs.
* Printing Messages::           Notifying users of progress or problems.


File: autoconf.info,  Node: Defining Symbols,  Next: Setting Output Variables,  Up: Results

Defining C Preprocessor Symbols
===============================

   A common action to take in response to a feature test is to define a
C preprocessor symbol indicating the results of the test.  That is done
by calling `AC_DEFINE' or `AC_DEFINE_UNQUOTED'.

   By default, `AC_OUTPUT' places the symbols defined by these macros
into the output variable `DEFS', which contains an option
`-DSYMBOL=VALUE' for each symbol defined.  Unlike in Autoconf version
1, there is no variable `DEFS' defined while `configure' is running.
To check whether Autoconf macros have already defined a certain C
preprocessor symbol, test the value of the appropriate cache variable,
as in this example:

     AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF))
     if test "$ac_cv_func_vprintf" != yes; then
     AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT))
     fi

   If `AC_CONFIG_HEADER' has been called, then instead of creating
`DEFS', `AC_OUTPUT' creates a header file by substituting the correct
values into `#define' statements in a template file.  *Note
Configuration Headers::, for more information about this kind of output.

 - Macro: AC_DEFINE (VARIABLE [, VALUE])
     Define C preprocessor variable VARIABLE.  If VALUE is given, set
     VARIABLE to that value (verbatim), otherwise set it to 1.  VALUE
     should not contain literal newlines, and if you are not using
     `AC_CONFIG_HEADER' it should not contain any `#' characters, as
     `make' tends to eat them.  To use a shell variable (which you need
     to do in order to define a value containing the `m4' quote
     characters `[' or `]'), use `AC_DEFINE_UNQUOTED' instead.  The
     following example defines the C preprocessor variable `EQUATION'
     to be the string constant `"$a > $b"':

          AC_DEFINE(EQUATION, "$a > $b")

 - Macro: AC_DEFINE_UNQUOTED (VARIABLE [, VALUE])
     Like `AC_DEFINE', but three shell expansions are
     performed--once--on VARIABLE and VALUE: variable expansion (`$'),
     command substitution (``'), and backslash escaping (`\').  Single
     and double quote characters in the value have no special meaning.
     Use this macro instead of `AC_DEFINE' when VARIABLE or VALUE is a
     shell variable.  Examples:

          AC_DEFINE_UNQUOTED(config_machfile, "${machfile}")
          AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
          AC_DEFINE_UNQUOTED(${ac_tr_hdr})

   Due to the syntactical bizarreness of the Bourne shell, do not use
semicolons to separate `AC_DEFINE' or `AC_DEFINE_UNQUOTED' calls from
other macro calls or shell code; that can cause syntax errors in the
resulting `configure' script.  Use either spaces or newlines.  That is,
do this:

     AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf")

or this:

     AC_CHECK_HEADER(elf.h,
       AC_DEFINE(SVR4)
       LIBS="$LIBS -lelf")

instead of this:

     AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf")


File: autoconf.info,  Node: Setting Output Variables,  Next: Caching Results,  Prev: Defining Symbols,  Up: Results

Setting Output Variables
========================

   One way to record the results of tests is to set "output variables",
which are shell variables whose values are substituted into files that
`configure' outputs.  The two macros below create new output variables.
*Note Preset Output Variables::, for a list of output variables that
are always available.

 - Macro: AC_SUBST (VARIABLE)
     Create an output variable from a shell variable.  Make `AC_OUTPUT'
     substitute the variable VARIABLE into output files (typically one
     or more `Makefile's).  This means that `AC_OUTPUT' will replace
     instances of `@VARIABLE@' in input files with the value that the
     shell variable VARIABLE has when `AC_OUTPUT' is called.  The value
     of VARIABLE should not contain literal newlines.

 - Macro: AC_SUBST_FILE (VARIABLE)
     Another way to create an output variable from a shell variable.
     Make `AC_OUTPUT' insert (without substitutions) the contents of
     the file named by shell variable VARIABLE into output files.  This
     means that `AC_OUTPUT' will replace instances of `@VARIABLE@' in
     output files (such as `Makefile.in') with the contents of the file
     that the shell variable VARIABLE names when `AC_OUTPUT' is called.
     Set the variable to `/dev/null' for cases that do not have a file
     to insert.

     This macro is useful for inserting `Makefile' fragments containing
     special dependencies or other `make' directives for particular host
     or target types into `Makefile's.  For example, `configure.in'
     could contain:

          AC_SUBST_FILE(host_frag)dnl
          host_frag=$srcdir/conf/sun4.mh

     and then a `Makefile.in' could contain:

          @host_frag@


File: autoconf.info,  Node: Caching Results,  Next: Printing Messages,  Prev: Setting Output Variables,  Up: Results

Caching Results
===============

   To avoid checking for the same features repeatedly in various
`configure' scripts (or repeated runs of one script), `configure' saves
the results of many of its checks in a "cache file".  If, when a
`configure' script runs, it finds a cache file, it reads from it the
results from previous runs and avoids rerunning those checks.  As a
result, `configure' can run much faster than if it had to perform all
of the checks every time.

 - Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT)
     Ensure that the results of the check identified by CACHE-ID are
     available.  If the results of the check were in the cache file
     that was read, and `configure' was not given the `--quiet' or
     `--silent' option, print a message saying that the result was
     cached; otherwise, run the shell commands COMMANDS-TO-SET-IT.
     Those commands should have no side effects except for setting the
     variable CACHE-ID.  In particular, they should not call
     `AC_DEFINE'; the code that follows the call to `AC_CACHE_VAL'
     should do that, based on the cached value.  Also, they should not
     print any messages, for example with `AC_MSG_CHECKING'; do that
     before calling `AC_CACHE_VAL', so the messages are printed
     regardless of whether the results of the check are retrieved from
     the cache or determined by running the shell commands.  If the
     shell commands are run to determine the value, the value will be
     saved in the cache file just before `configure' creates its output
     files.  *Note Cache Variable Names::, for how to choose the name
     of the CACHE-ID variable.

* Menu:

* Cache Variable Names::        Shell variables used in caches.
* Cache Files::	        	Files `configure' uses for caching.


File: autoconf.info,  Node: Cache Variable Names,  Next: Cache Files,  Up: Caching Results

Cache Variable Names
--------------------

   The names of cache variables should have the following format:

     PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE[_ADDITIONAL-OPTIONS]

for example, `ac_cv_header_stat_broken' or
`ac_cv_prog_gcc_traditional'.  The parts of the variable name are:

PACKAGE-PREFIX
     An abbreviation for your package or organization; the same prefix
     you begin local Autoconf macros with, except lowercase by
     convention.  For cache values used by the distributed Autoconf
     macros, this value is `ac'.

`_cv_'
     Indicates that this shell variable is a cache value.

VALUE-TYPE
     A convention for classifying cache values, to produce a rational
     naming system.  The values used in Autoconf are listed in *Note
     Macro Names::.

SPECIFIC-VALUE
     Which member of the class of cache values this test applies to.
     For example, which function (`alloca'), program (`gcc'), or output
     variable (`INSTALL').

ADDITIONAL-OPTIONS
     Any particular behavior of the specific member that this test
     applies to.  For example, `broken' or `set'.  This part of the
     name may be omitted if it does not apply.

   Like their names, the values that may be assigned to cache variables
have a few restrictions.  The values may not contain single quotes or
curly braces.  Usually, their values will be boolean (`yes' or `no') or
the names of files or functions; so this is not an important
restriction.


File: autoconf.info,  Node: Cache Files,  Prev: Cache Variable Names,  Up: Caching Results

Cache Files
-----------

   A cache file is a shell script that caches the results of configure
tests run on one system so they can be shared between configure scripts
and configure runs.  It is not useful on other systems.  If its contents
are invalid for some reason, the user may delete or edit it.

   By default, configure uses `./config.cache' as the cache file,
creating it if it does not exist already.  `configure' accepts the
`--cache-file=FILE' option to use a different cache file; that is what
`configure' does when it calls `configure' scripts in subdirectories,
so they share the cache.  Giving `--cache-file=/dev/null' disables
caching, for debugging `configure'.  *Note Subdirectories::, for
information on configuring subdirectories with the `AC_CONFIG_SUBDIRS'
macro.  `config.status' only pays attention to the cache file if it is
given the `--recheck' option, which makes it rerun `configure'.

   It is wrong to try to distribute cache files for particular system
types.  There is too much room for error in doing that, and too much
administrative overhead in maintaining them.  For any features that
can't be guessed automatically, use the standard method of the canonical
system type and linking files (*note Manual Configuration::.).

   The cache file on a particular system will gradually accumulate
whenever someone runs a `configure' script; it will be initially
nonexistent.  Running `configure' merges the new cache results with the
existing cache file.  The site initialization script can specify a
site-wide cache file to use instead of the default, to make it work
transparently, as long as the same C compiler is used every time (*note
Site Defaults::.).


File: autoconf.info,  Node: Printing Messages,  Prev: Caching Results,  Up: Results

Printing Messages
=================

   `configure' scripts need to give users running them several kinds of
information.  The following macros print messages in ways appropriate
for each kind.  The arguments to all of them get enclosed in shell
double quotes, so the shell performs variable and backquote substitution
on them.

   These macros are all wrappers around the `echo' shell command.
`configure' scripts should rarely need to run `echo' directly to print
messages for the user.  Using these macros makes it easy to change how
and when each kind of message is printed; such changes need only be
made to the macro definitions, and all of the callers change
automatically.

 - Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION)
     Notify the user that `configure' is checking for a particular
     feature.  This macro prints a message that starts with `checking '
     and ends with `...' and no newline.  It must be followed by a call
     to `AC_MSG_RESULT' to print the result of the check and the
     newline.  The FEATURE-DESCRIPTION should be something like
     `whether the Fortran compiler accepts C++ comments' or `for c89'.

     This macro prints nothing if `configure' is run with the `--quiet'
     or `--silent' option.

 - Macro: AC_MSG_RESULT (RESULT-DESCRIPTION)
     Notify the user of the results of a check.  RESULT-DESCRIPTION is
     almost always the value of the cache variable for the check,
     typically `yes', `no', or a file name.  This macro should follow a
     call to `AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be
     the completion of the message printed by the call to
     `AC_MSG_CHECKING'.

     This macro prints nothing if `configure' is run with the `--quiet'
     or `--silent' option.

 - Macro: AC_MSG_ERROR (ERROR-DESCRIPTION)
     Notify the user of an error that prevents `configure' from
     completing.  This macro prints an error message on the standard
     error stream and exits `configure' with a nonzero status.
     eRROR-DESCRIPTION should be something like `invalid value $HOME
     for \$HOME'.

 - Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION)
     Notify the `configure' user of a possible problem.  This macro
     prints the message on the standard error stream; `configure'
     continues running afterward, so macros that call `AC_MSG_WARN'
     should provide a default (back-up) behavior for the situations
     they warn about.  PROBLEM-DESCRIPTION should be something like `ln
     -s seems to make hard links'.

   The following two macros are an obsolete alternative to
`AC_MSG_CHECKING' and `AC_MSG_RESULT'.

 - Macro: AC_CHECKING (FEATURE-DESCRIPTION)
     This macro is similar to `AC_MSG_CHECKING', except that it prints a
     newline after the FEATURE-DESCRIPTION.  It is useful mainly to
     print a general description of the overall purpose of a group of
     feature checks, e.g.,

          AC_CHECKING(if stack overflow is detectable)

 - Macro: AC_VERBOSE (RESULT-DESCRIPTION)
     This macro is similar to `AC_MSG_RESULT', except that it is meant
     to follow a call to `AC_CHECKING' instead of `AC_MSG_CHECKING'; it
     starts the message it prints with a tab.  It is considered
     obsolete.


File: autoconf.info,  Node: Writing Macros,  Next: Manual Configuration,  Prev: Results,  Up: Top

Writing Macros
**************

   When you write a feature test that could be applicable to more than
one software package, the best thing to do is encapsulate it in a new
macro.  Here are some instructions and guidelines for writing Autoconf
macros.

* Menu:

* Macro Definitions::		Basic format of an Autoconf macro.
* Macro Names::                 What to call your new macros.
* Quoting::			Protecting macros from unwanted expansion.
* Dependencies Between Macros::	What to do when macros depend on other macros.


File: autoconf.info,  Node: Macro Definitions,  Next: Macro Names,  Up: Writing Macros

Macro Definitions
=================

   Autoconf macros are defined using the `AC_DEFUN' macro, which is
similar to the `m4' builtin `define' macro.  In addition to defining a
macro, `AC_DEFUN' adds to it some code which is used to constrain the
order in which macros are called (*note Prerequisite Macros::.).

   An Autoconf macro definition looks like this:

     AC_DEFUN(MACRO-NAME, [MACRO-BODY])

The square brackets here do not indicate optional text: they should
literally be present in the macro definition to avoid macro expansion
problems (*note Quoting::.).  You can refer to any arguments passed to
the macro as `$1', `$2', etc.

   To introduce comments in `m4', use the `m4' builtin `dnl'; it causes
`m4' to discard the text through the next newline.  It is not needed
between macro definitions in `acsite.m4' and `aclocal.m4', because all
output is discarded until `AC_INIT' is called.

   *Note How to define new macros: (m4.info)Definitions, for more
complete information on writing `m4' macros.


File: autoconf.info,  Node: Macro Names,  Next: Quoting,  Prev: Macro Definitions,  Up: Writing Macros

Macro Names
===========

   All of the Autoconf macros have all-uppercase names starting with
`AC_' to prevent them from accidentally conflicting with other text.
All shell variables that they use for internal purposes have
mostly-lowercase names starting with `ac_'.  To ensure that your macros
don't conflict with present or future Autoconf macros, you should
prefix your own macro names and any shell variables they use with some
other sequence.  Possibilities include your initials, or an abbreviation
for the name of your organization or software package.

   Most of the Autoconf macros' names follow a structured naming
convention that indicates the kind of feature check by the name.  The
macro names consist of several words, separated by underscores, going
from most general to most specific.   The names of their cache
variables use the same convention (*note Cache Variable Names::., for
more information on them).

   The first word of the name after `AC_' usually tells the category of
feature being tested.  Here are the categories used in Autoconf for
specific test macros, the kind of macro that you are more likely to
write.  They are also used for cache variables, in all-lowercase.  Use
them where applicable; where they're not, invent your own categories.

`C'
     C language builtin features.

`DECL'
     Declarations of C variables in header files.

`FUNC'
     Functions in libraries.

`GROUP'
     UNIX group owners of files.

`HEADER'
     Header files.

`LIB'
     C libraries.

`PATH'
     The full path names to files, including programs.

`PROG'
     The base names of programs.

`STRUCT'
     Definitions of C structures in header files.

`SYS'
     Operating system features.

`TYPE'
     C builtin or declared types.

`VAR'
     C variables in libraries.

   After the category comes the name of the particular feature being
tested.  Any further words in the macro name indicate particular aspects
of the feature.  For example, `AC_FUNC_UTIME_NULL' checks the behavior
of the `utime' function when called with a `NULL' pointer.

   A macro that is an internal subroutine of another macro should have a
name that starts with the name of that other macro, followed by one or
more words saying what the internal macro does.  For example,
`AC_PATH_X' has internal macros `AC_PATH_X_XMKMF' and
`AC_PATH_X_DIRECT'.


File: autoconf.info,  Node: Quoting,  Next: Dependencies Between Macros,  Prev: Macro Names,  Up: Writing Macros

Quoting
=======

   Macros that are called by other macros are evaluated by `m4' several
times; each evaluation might require another layer of quotes to prevent
unwanted expansions of macros or `m4' builtins, such as `define' and
`$1'.  Quotes are also required around macro arguments that contain
commas, since commas separate the arguments from each other.  It's a
good idea to quote any macro arguments that contain newlines or calls
to other macros, as well.

   Autoconf changes the `m4' quote characters from the default ``' and
`'' to `[' and `]', because many of the macros use ``' and `'',
mismatched.  However, in a few places the macros need to use brackets
(usually in C program text or regular expressions).  In those places,
they use the `m4' builtin command `changequote' to temporarily change
the quote characters to `<<' and `>>'.  (Sometimes, if they don't need
to quote anything, they disable quoting entirely instead by setting the
quote characters to empty strings.)  Here is an example:

     AC_TRY_LINK(
     changequote(<<, >>)dnl
     <<#include <time.h>
     #ifndef tzname /* For SGI.  */
     extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
     #endif>>,
     changequote([, ])dnl
     [atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)

   When you create a `configure' script using newly written macros,
examine it carefully to check whether you need to add more quotes in
your macros.  If one or more words have disappeared in the `m4' output,
you need more quotes.  When in doubt, quote.

   However, it's also possible to put on too many layers of quotes.  If
this happens, the resulting `configure' script will contain unexpanded
macros.  The `autoconf' program checks for this problem by doing `grep
AC_ configure'.


File: autoconf.info,  Node: Dependencies Between Macros,  Prev: Quoting,  Up: Writing Macros

Dependencies Between Macros
===========================

   Some Autoconf macros depend on other macros having been called first
in order to work correctly.  Autoconf provides a way to ensure that
certain macros are called if needed and a way to warn the user if
macros are called in an order that might cause incorrect operation.

* Menu:

* Prerequisite Macros::		Ensuring required information.
* Suggested Ordering::		Warning about possible ordering problems.
* Obsolete Macros::             Warning about old ways of doing things.


File: autoconf.info,  Node: Prerequisite Macros,  Next: Suggested Ordering,  Up: Dependencies Between Macros

Prerequisite Macros
-------------------

   A macro that you write might need to use values that have previously
been computed by other macros.  For example, `AC_DECL_YYTEXT' examines
the output of `flex' or `lex', so it depends on `AC_PROG_LEX' having
been called first to set the shell variable `LEX'.

   Rather than forcing the user of the macros to keep track of the
dependencies between them, you can use the `AC_REQUIRE' macro to do it
automatically.  `AC_REQUIRE' can ensure that a macro is only called if
it is needed, and only called once.

 - Macro: AC_REQUIRE (MACRO-NAME)
     If the `m4' macro MACRO-NAME has not already been called, call it
     (without any arguments).  Make sure to quote MACRO-NAME with
     square brackets.  MACRO-NAME must have been defined using
     `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that
     it has been called.

   An alternative to using `AC_DEFUN' is to use `define' and call
`AC_PROVIDE'.  Because this technique does not prevent nested messages,
it is considered obsolete.

 - Macro: AC_PROVIDE (THIS-MACRO-NAME)
     Record the fact that THIS-MACRO-NAME has been called.
     tHIS-MACRO-NAME should be the name of the macro that is calling
     `AC_PROVIDE'.  An easy way to get it is from the `m4' builtin
     variable `$0', like this:

          AC_PROVIDE([$0])


File: autoconf.info,  Node: Suggested Ordering,  Next: Obsolete Macros,  Prev: Prerequisite Macros,  Up: Dependencies Between Macros

Suggested Ordering
------------------

   Some macros should be run before another macro if both are called,
but neither *requires* that the other be called.  For example, a macro
that changes the behavior of the C compiler should be called before any
macros that run the C compiler.  Many of these dependencies are noted in
the documentation.

   Autoconf provides the `AC_BEFORE' macro to warn users when macros
with this kind of dependency appear out of order in a `configure.in'
file.  The warning occurs when creating `configure' from
`configure.in', not when running `configure'.  For example,
`AC_PROG_CPP' checks whether the C compiler can run the C preprocessor
when given the `-E' option.  It should therefore be called after any
macros that change which C compiler is being used, such as
`AC_PROG_CC'.  So `AC_PROG_CC' contains:

     AC_BEFORE([$0], [AC_PROG_CPP])dnl

This warns the user if a call to `AC_PROG_CPP' has already occurred
when `AC_PROG_CC' is called.

 - Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME)
     Make `m4' print a warning message on the standard error output if
     CALLED-MACRO-NAME has already been called.  THIS-MACRO-NAME should
     be the name of the macro that is calling `AC_BEFORE'.  The macro
     CALLED-MACRO-NAME must have been defined using `AC_DEFUN' or else
     contain a call to `AC_PROVIDE' to indicate that it has been called.


File: autoconf.info,  Node: Obsolete Macros,  Prev: Suggested Ordering,  Up: Dependencies Between Macros

Obsolete Macros
---------------

   Configuration and portability technology has evolved over the years.
Often better ways of solving a particular problem are developed, or
ad-hoc approaches are systematized.  This process has occurred in many
parts of Autoconf.  One result is that some of the macros are now
considered "obsolete"; they still work, but are no longer considered
the best thing to do.  Autoconf provides the `AC_OBSOLETE' macro to
warn users producing `configure' scripts when they use obsolete macros,
to encourage them to modernize.  A sample call is:

     AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl

 - Macro: AC_OBSOLETE (THIS-MACRO-NAME [, SUGGESTION])
     Make `m4' print a message on the standard error output warning that
     THIS-MACRO-NAME is obsolete, and giving the file and line number
     where it was called.  THIS-MACRO-NAME should be the name of the
     macro that is calling `AC_OBSOLETE'.  If SUGGESTION is given, it
     is printed at the end of the warning message; for example, it can
     be a suggestion for what to use instead of THIS-MACRO-NAME.


File: autoconf.info,  Node: Manual Configuration,  Next: Site Configuration,  Prev: Writing Macros,  Up: Top

Manual Configuration
********************

   A few kinds of features can't be guessed automatically by running
test programs.  For example, the details of the object file format, or
special options that need to be passed to the compiler or linker.  It is
possible to check for such features using ad-hoc means, such as having
`configure' check the output of the `uname' program, or looking for
libraries that are unique to particular systems.  However, Autoconf
provides a uniform method for handling unguessable features.

* Menu:

* Specifying Names::            Specifying the system type.
* Canonicalizing::              Getting the canonical system type.
* System Type Variables::       Variables containing the system type.
* Using System Type::           What to do with the system type.


File: autoconf.info,  Node: Specifying Names,  Next: Canonicalizing,  Up: Manual Configuration

Specifying the System Type
==========================

   Like other GNU `configure' scripts, Autoconf-generated `configure'
scripts can make decisions based on a canonical name for the system
type, which has the form:

     CPU-COMPANY-SYSTEM

   `configure' can usually guess the canonical name for the type of
system it's running on.  To do so it runs a script called
`config.guess', which derives the name using the `uname' command or
symbols predefined by the C preprocessor.

   Alternately, the user can specify the system type with command line
arguments to `configure'.  Doing so is necessary when cross-compiling.
In the most complex case of cross-compiling, three system types are
involved.  The options to specify them are:

`--build=BUILD-TYPE'
     the type of system on which the package is being configured and
     compiled (rarely needed);

`--host=HOST-TYPE'
     the type of system on which the package will run;

`--target=TARGET-TYPE'
     the type of system for which any compiler tools in the package will
     produce code.

If the user gives `configure' a non-option argument, it is used as the
default for the host, target, and build system types if the user does
not specify them explicitly with options.  The target and build types
default to the host type if it is given and they are not.  If you are
cross-compiling, you still have to specify the names of the cross-tools
you use, in particular the C compiler, on the `configure' command line,
e.g.,

     CC=m68k-coff-gcc configure --target=m68k-coff

   `configure' recognizes short aliases for many system types; for
example, `decstation' can be given on the command line instead of
`mips-dec-ultrix4.2'.  `configure' runs a script called `config.sub' to
canonicalize system type aliases.


File: autoconf.info,  Node: Canonicalizing,  Next: System Type Variables,  Prev: Specifying Names,  Up: Manual Configuration

Getting the Canonical System Type
=================================

   The following macros make the system type available to `configure'
scripts.  They run the shell script `config.guess' to determine any
values for the host, target, and build types that they need and the user
did not specify on the command line.  They run `config.sub' to
canonicalize any aliases the user gave.  If you use these macros, you
must distribute those two shell scripts along with your source code.
*Note Output::, for information about the `AC_CONFIG_AUX_DIR' macro
which you can use to control which directory `configure' looks for
those scripts in.  If you do not use either of these macros,
`configure' ignores any `--host', `--target', and `--build' options
given to it.

 - Macro: AC_CANONICAL_SYSTEM
     Determine the system type and set output variables to the names of
     the canonical system types.  *Note System Type Variables::, for
     details about the variables this macro sets.

 - Macro: AC_CANONICAL_HOST
     Perform only the subset of `AC_CANONICAL_SYSTEM' relevant to the
     host type.  This is all that is needed for programs that are not
     part of a compiler toolchain.


File: autoconf.info,  Node: System Type Variables,  Next: Using System Type,  Prev: Canonicalizing,  Up: Manual Configuration

System Type Variables
=====================

   After calling `AC_CANONICAL_SYSTEM', the following output variables
contain the system type information.  After `AC_CANONICAL_HOST', only
the `host' variables below are set.

``build', `host', `target''
     the canonical system names;

``build_alias', `host_alias', `target_alias''
     the names the user specified, or the canonical names if
     `config.guess' was used;

``build_cpu', `build_vendor', `build_os''
``host_cpu', `host_vendor', `host_os''
``target_cpu', `target_vendor', `target_os''
     the individual parts of the canonical names (for convenience).


File: autoconf.info,  Node: Using System Type,  Prev: System Type Variables,  Up: Manual Configuration

Using the System Type
=====================

   How do you use a canonical system type?  Usually, you use it in one
or more `case' statements in `configure.in' to select system-specific C
files.  Then link those files, which have names based on the system
name, to generic names, such as `host.h' or `target.c'.  The `case'
statement patterns can use shell wildcards to group several cases
together, like in this fragment:

     case "$target" in
     i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;;
     i960-*-bout) obj_format=bout ;;
     esac

 - Macro: AC_LINK_FILES (SOURCE..., DEST...)
     Make `AC_OUTPUT' link each of the existing files SOURCE to the
     corresponding link name DEST.  Makes a symbolic link if possible,
     otherwise a hard link.  The DEST and SOURCE names should be
     relative to the top level source or build directory.

     For example, this call:

          AC_LINK_FILES(config/${machine}.h config/${obj_format}.h, host.h object.h)

     creates in the current directory `host.h', which is a link to
     `SRCDIR/config/${machine}.h', and `object.h', which is a link to
     `SRCDIR/config/${obj_format}.h'.


File: autoconf.info,  Node: Site Configuration,  Next: Invoking configure,  Prev: Manual Configuration,  Up: Top

Site Configuration
******************

   `configure' scripts support several kinds of local configuration
decisions.  There are ways for users to specify where external software
packages are, include or exclude optional features, install programs
under modified names, and set default values for `configure' options.

* Menu:

* External Software::           Working with other optional software.
* Package Options::             Selecting optional features.
* Site Details::                Configuring site details.
* Transforming Names::          Changing program names when installing.
* Site Defaults::               Giving `configure' local defaults.


File: autoconf.info,  Node: External Software,  Next: Package Options,  Up: Site Configuration

Working With External Software
==============================

   Some packages require, or can optionally use, other software packages
which are already installed.  The user can give `configure' command
line options to specify which such external software to use.  The
options have one of these forms:

     --with-PACKAGE[=ARG]
     --without-PACKAGE

   For example, `--with-gnu-ld' means work with the GNU linker instead
of some other linker.  `--with-x11' means work with X11.

   The user can give an argument by following the package name with `='
and the argument.  Giving an argument of `no' is for packages that are
used by default; it says to *not* use the package.  An argument that is
neither `yes' nor `no' could include a name or number of a version of
the other package, to specify more precisely which other package this
program is supposed to work with.  If no argument is given, it defaults
to `yes'.  `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'.

   For each external software package that may be used, `configure.in'
should call `AC_ARG_WITH' to detect whether the `configure' user asked
to use it.  Whether each package is used or not by default, and which
arguments are valid, is up to you.

 - Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, ACTION-IF-TRUE [,
          ACTION-IF-FALSE])
     If the user gave `configure' the option `--with-PACKAGE' or
     `--without-PACKAGE', run shell commands ACTION-IF-TRUE.  Otherwise
     run shell commands ACTION-IF-FALSE.  The name PACKAGE indicates
     another software package that this program should work with.  It
     should consist only of alphanumeric characters and dashes.

     The option's argument is available to the shell commands
     ACTION-IF-TRUE in the shell variable `withval'.

     The argument HELP-STRING is a description of the option which
     looks like this:
            --with-readline         support fancy command line editing

     HELP-STRING may be more than one line long, if more detail is
     needed.  Just make sure the columns line up in `configure --help'.
     Avoid tabs in the help string.  You'll need to enclose it in `['
     and `]' in order to produce the leading spaces.

 - Macro: AC_WITH (PACKAGE, ACTION-IF-TRUE [, ACTION-IF-FALSE])
     This is an obsolete version of `AC_ARG_WITH' that does not support
     providing a help string.


File: autoconf.info,  Node: Package Options,  Next: Site Details,  Prev: External Software,  Up: Site Configuration

Choosing Package Options
========================

   If a software package has optional compile-time features, the user
can give `configure' command line options to specify whether to compile
them.  The options have one of these forms:

     --enable-FEATURE[=ARG]
     --disable-FEATURE

   These options allow users to choose which optional features to build
and install.  `--enable-FEATURE' options should never make a feature
behave differently or cause one feature to replace another.  They
should only cause parts of the program to be built rather than left out.

   The user can give an argument by following the feature name with `='
and the argument.  Giving an argument of `no' requests that the feature
*not* be made available.  A feature with an argument looks like
`--enable-debug=stabs'.  If no argument is given, it defaults to `yes'.
`--disable-FEATURE' is equivalent to `--enable-FEATURE=no'.

   For each optional feature, `configure.in' should call
`AC_ARG_ENABLE' to detect whether the `configure' user asked to include
it.  Whether each feature is included or not by default, and which
arguments are valid, is up to you.

 - Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, ACTION-IF-TRUE [,
          ACTION-IF-FALSE])
     If the user gave `configure' the option `--enable-FEATURE' or
     `--disable-FEATURE', run shell commands ACTION-IF-TRUE.  Otherwise
     run shell commands ACTION-IF-FALSE.  The name FEATURE indicates an
     optional user-level facility.  It should consist only of
     alphanumeric characters and dashes.

     The option's argument is available to the shell commands
     ACTION-IF-TRUE in the shell variable `enableval'.  The HELP-STRING
     argument is like that of `AC_ARG_WITH' (*note External
     Software::.).

 - Macro: AC_ENABLE (FEATURE, ACTION-IF-TRUE [, ACTION-IF-FALSE])
     This is an obsolete version of `AC_ARG_ENABLE' that does not
     support providing a help string.


File: autoconf.info,  Node: Site Details,  Next: Transforming Names,  Prev: Package Options,  Up: Site Configuration

Configuring Site Details
========================

   Some software packages require complex site-specific information.
Some examples are host names to use for certain services, company
names, and email addresses to contact.  Since some configuration
scripts generated by Metaconfig ask for such information interactively,
people sometimes wonder how to get that information in
Autoconf-generated configuration scripts, which aren't interactive.

   Such site configuration information should be put in a file that is
edited *only by users*, not by programs.  The location of the file can
either be based on the `prefix' variable, or be a standard location
such as the user's home directory.  It could even be specified by an
environment variable.  The programs should examine that file at run
time, rather than at compile time.  That approach is more convenient
for users and makes the configuration process simpler than getting the
information while configuring.  *Note Variables for Installation
Directories: (standards)Directory Variables, for more information on
where to put data files.