2004-10-27 Stepan Kasal * doc/autoconf.texi (Alternative Programs): Rename the node to ... (Programs): ... this. Add a general information, ... (Generic Programs): ... removing it from the description of individual macros. (Particular Programs, AC_PROG_GREP): Improve a formulation. --- doc/autoconf.texi.a2 2004-10-27 11:12:47.000000000 +0200 +++ doc/autoconf.texi 2004-10-27 11:31:27.000000000 +0200 @@ -325,7 +325,7 @@ Existing Tests * Common Behavior:: Macros' standard schemes -* Alternative Programs:: Selecting between alternative programs +* Programs:: Selecting between alternative programs * Files:: Checking for the existence of files * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -342,7 +342,7 @@ * Standard Symbols:: Symbols defined by the macros * Default Includes:: Includes used by the generic macros -Alternative Programs +Programs * Particular Programs:: Special handling to find certain programs * Generic Programs:: How to find other programs @@ -3078,7 +3078,7 @@ @menu * Common Behavior:: Macros' standard schemes -* Alternative Programs:: Selecting between alternative programs +* Programs:: Selecting between alternative programs * Files:: Checking for the existence of files * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -3212,16 +3212,38 @@ @code{HAVE_STRINGS_H} won't. @end defmac address@hidden Alternative Programs address@hidden Alternative Programs address@hidden Programs address@hidden Programs @cindex Programs, checking These macros check for the presence or behavior of particular programs. -They are used to choose between several alternative programs and to -decide what to do once one has been chosen. If there is no macro -specifically defined to check for a program you need, and you don't need -to check for any special properties of it, then you can use one of the -general program-check macros. +They are also used to choose between several alternative programs and to +decide what to do once one has been chosen. + +If there is no macro specifically defined to check for a program you +need, and you don't need to check for any special properties of it, then +you can use one of the general program-check macros. + +These macros work with an environment variable, eg.@ @code{GREP}; for +the generic macros, you specify the variable name as the first +parameter. + +If the variable is already set, the macro does nothing. + +If it is not set, it looks for the program. If the program is found, +it's name is assigned to the variable. (Or name with parameters, or +full pathname, it depends on the individual macros.) If the program is +not found and the optional parameter @var{value-if-not-found} was +specified, that value is assigned to the variable. + +All these macros call AC_SUBST on the variable. + +As the result depends on the initial value of the variable, it should +be declared as precious. This is done automatically by the specific +tests. For the generic macros, you are strongly encouradged to declare +the variable as precious, @xref{Setting Output Variables}, address@hidden, for more details. (Another possibility would be +to unset the variable before calling the macro.) @menu * Particular Programs:: Special handling to find certain programs @@ -3252,8 +3274,8 @@ single @option{-e} option. This macro looks for @sc{gnu} Grep or else the best available @code{grep} or @code{ggrep} in the user's @code{$PATH} which accepts the longest input lines possible, and which -accepts and respects multiple @option{-e} options. Set the -output variable @code{GREP} to whatever is chosen. +accepts and respects multiple @option{-e} options. It sets the output +variable @code{GREP} to whatever is chosen. @end defmac @defmac AC_PROG_EGREP @@ -3433,9 +3455,7 @@ @var{value-if-not-found}, if given. Always pass over @var{reject} (an absolute file name) even if it is the first found in the search path; in that case, set @var{variable} using the absolute file name of the address@hidden found that is not @var{reject}. If address@hidden was already set, do nothing. Calls @code{AC_SUBST} for address@hidden address@hidden found that is not @var{reject}. @end defmac @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) @@ -3444,9 +3464,8 @@ @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set @var{variable} to the name of that program. Otherwise, continue checking the next program in the list. If none of the programs in the -list are found, set @var{variable} to @var{value-if-not-found}; if address@hidden is not specified, the value of @var{variable} -is not changed. Calls @code{AC_SUBST} for @var{variable}. +list are found, set @var{variable} to @var{value-if-not-found} (if it is +specified). @end defmac @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) @@ -3496,9 +3515,7 @@ prefix, and if the build and target types are equal, then the first one without a prefix is used. If a tool is found, set @var{variable} to the name of that program. If none of the tools in the list are found, -set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found} -is not specified, the value of @var{variable} is not changed. Calls address@hidden for @var{variable}. +set @var{variable} to @var{value-if-not-found}, if it is given. @end defmac @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) @@ -3509,9 +3526,8 @@ (@pxref{Canonicalizing}). If none of the tools can be found with a prefix, then the first one without a prefix is used. If a tool is found, set @var{variable} to the name of that program. If none of the tools in -the list are found, set @var{variable} to @var{value-if-not-found}; if address@hidden is not specified, the value of @var{variable} -is not changed. Calls @code{AC_SUBST} for @var{variable}. +the list are found, set @var{variable} to @var{value-if-not-found}, if +specified. In the future, when cross-compiling this macro will @emph{not} accept program names that are not prefixed with the host type.