autoconf: Setting Output Variables

1 
1 7.2 Setting Output Variables
1 ============================
1 
1 Another way to record the results of tests is to set "output
1 variables", which are shell variables whose values are substituted into
1 files that `configure' outputs.  The two macros below create new output
1 variables.  ⇒Preset Output Variables, for a list of output
1 variables that are always available.
1 
1  -- Macro: AC_SUBST (VARIABLE, [VALUE])
1      Create an output variable from a shell variable.  Make `AC_OUTPUT'
1      substitute the variable VARIABLE into output files (typically one
1      or more makefiles).  This means that `AC_OUTPUT' replaces
1      instances of `@VARIABLE@' in input files with the value that the
1      shell variable VARIABLE has when `AC_OUTPUT' is called.  The value
1      can contain any non-`NUL' character, including newline.  If you
1      are using Automake 1.11 or newer, for newlines in values you might
1      want to consider using `AM_SUBST_NOTMAKE' to prevent `automake'
1      from adding a line `VARIABLE = @VARIABLE@' to the `Makefile.in'
1      files (⇒Automake (automake)Optional.).
1 
1      Variable occurrences should not overlap: e.g., an input file should
1      not contain `@VAR1@VAR2@' if VAR1 and VAR2 are variable names.
1      The substituted value is not rescanned for more output variables;
1      occurrences of `@VARIABLE@' in the value are inserted literally
1      into the output file.  (The algorithm uses the special marker
1      `|#_!!_#|' internally, so neither the substituted value nor the
1      output file may contain `|#_!!_#|'.)
1 
1      If VALUE is given, in addition assign it to VARIABLE.
1 
11      The string VARIABLE is passed to `m4_pattern_allow' (⇒
      Forbidden Patterns).
1 
1  -- Macro: AC_SUBST_FILE (VARIABLE)
1      Another way to create an output variable from a shell variable.
1      Make `AC_OUTPUT' insert (without substitutions) the contents of
1      the file named by shell variable VARIABLE into output files.  This
1      means that `AC_OUTPUT' replaces instances of `@VARIABLE@' in
1      output files (such as `Makefile.in') with the contents of the file
1      that the shell variable VARIABLE names when `AC_OUTPUT' is called.
1      Set the variable to `/dev/null' for cases that do not have a file
1      to insert.  This substitution occurs only when the `@VARIABLE@' is
1      on a line by itself, optionally surrounded by spaces and tabs.  The
1      substitution replaces the whole line, including the spaces, tabs,
1      and the terminating newline.
1 
1      This macro is useful for inserting makefile fragments containing
1      special dependencies or other `make' directives for particular host
1      or target types into makefiles.  For example, `configure.ac' could
1      contain:
1 
1           AC_SUBST_FILE([host_frag])
1           host_frag=$srcdir/conf/sun4.mh
1 
1      and then a `Makefile.in' could contain:
1 
1           @host_frag@
1 
11      The string VARIABLE is passed to `m4_pattern_allow' (⇒
      Forbidden Patterns).
1 
1    Running `configure' in varying environments can be extremely
1 dangerous.  If for instance the user runs `CC=bizarre-cc ./configure',
1 then the cache, `config.h', and many other output files depend upon
1 `bizarre-cc' being the C compiler.  If for some reason the user runs
1 `./configure' again, or if it is run via `./config.status --recheck',
1 (⇒Automatic Remaking, and ⇒config.status Invocation),
1 then the configuration can be inconsistent, composed of results
1 depending upon two different compilers.
1 
1    Environment variables that affect this situation, such as `CC'
1 above, are called "precious variables", and can be declared as such by
1 `AC_ARG_VAR'.
1 
1  -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION)
1      Declare VARIABLE is a precious variable, and include its
1      DESCRIPTION in the variable section of `./configure --help'.
1 
1      Being precious means that
1         - VARIABLE is substituted via `AC_SUBST'.
1 
1         - The value of VARIABLE when `configure' was launched is saved
1           in the cache, including if it was not specified on the command
1           line but via the environment.  Indeed, while `configure' can
1           notice the definition of `CC' in `./configure CC=bizarre-cc',
1           it is impossible to notice it in `CC=bizarre-cc ./configure',
1           which, unfortunately, is what most users do.
1 
1           We emphasize that it is the _initial_ value of VARIABLE which
1           is saved, not that found during the execution of `configure'.
1           Indeed, specifying `./configure FOO=foo' and letting
1           `./configure' guess that `FOO' is `foo' can be two different
1           things.
1 
1         - VARIABLE is checked for consistency between two `configure'
1           runs.  For instance:
1 
1                $ ./configure --silent --config-cache
1                $ CC=cc ./configure --silent --config-cache
1                configure: error: `CC' was not set in the previous run
1                configure: error: changes in the environment can compromise \
1                the build
1                configure: error: run `make distclean' and/or \
1                `rm config.cache' and start over
1 
1           and similarly if the variable is unset, or if its content is
1           changed.  If the content has white space changes only, then
1           the error is degraded to a warning only, but the old value is
1           reused.
1 
11         - VARIABLE is kept during automatic reconfiguration (⇒
           config.status Invocation) as if it had been passed as a
1           command line argument, including when no cache is used:
1 
1                $ CC=/usr/bin/cc ./configure var=raboof --silent
1                $ ./config.status --recheck
1                running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
1                  CC=/usr/bin/cc  --no-create --no-recursion
1