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