9.2 Setting Output Variables

One way to record the results of tests is to set output variables. These are ordinary shell variables that are set in configure. Their values are substituted into files that configure outputs, replacing occurrences of ‘@variable@’ in an input file with the values that configure has determined for the variables. Any occurrences of ‘@variable@’ for other variables are left unchanged.

For example, each subdirectory in a distribution that contains something to be compiled or installed should come with a file Makefile.in. configure creates a file Makefile in that directory by substituting the output variables in Makefile.in. A software package that uses a configure script should be distributed with a file Makefile.in, but no makefile; that way, the user has to properly configure the package for the local system before compiling it.

Macro: AC_CONFIG_FILES (file…, [cmds], [init-cmds])

Make AC_OUTPUT create each file by copying an input file (by default file.in), substituting the output variable values. This macro is one of the instantiating macros; see Configuration Actions. This macro creates the directory that the file is in if it doesn’t exist. Usually, makefiles are created this way, but other files, such as .gdbinit, can be specified as well.

Typical calls to AC_CONFIG_FILES look like this:

AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])

You can override an input file name by appending a colon-separated list of input files to file. Examples:

AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
                [lib/Makefile:boiler/lib.mk])

Doing this allows you to keep your file names acceptable to DOS variants, or to prepend and/or append boilerplate to the file.

The two macros below create new output variables. See Preset Output Variables for a list of output variables that are always available.

Macro: AC_SUBST (variable, [value])

Create an output variable from a shell variable. If value is given, assign it to variable.

Make AC_OUTPUT substitute the variable variable into output files (typically one or more makefiles). This means that AC_OUTPUT replaces instances of ‘@variable@’ in input files with the value that the shell variable variable has when AC_OUTPUT is called. The value can contain any non-NUL character, including newline.

If you are using Automake 1.11 or newer, automake adds a line variable = @variable@ to the Makefile.in files (see Other macros Automake recognizes). If you want to avoid this (for example for newlines in values) use AM_SUBST_NOTMAKE instead (see Other macros Automake recognizes).

Variable occurrences should not overlap: e.g., an input file should not contain ‘@var1@var2@’ if var1 and var2 are variable names. The substituted value is not rescanned for more output variables; occurrences of ‘@variable@’ in the value are inserted literally into the output file. (The algorithm uses the special marker |#_!!_#| internally, so neither the substituted value nor the output file may contain |#_!!_#|.)

The string variable is passed to m4_pattern_allow (see Forbidden Patterns). variable is not further expanded, even if there is another macro by the same name.

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 replaces 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 substitution occurs only when the ‘@variable@’ is on a line by itself, optionally surrounded by spaces and tabs. The substitution replaces the whole line, including the spaces, tabs, and the terminating newline.

This macro is useful for inserting makefile fragments containing special dependencies or other make directives for particular host or target types into makefiles. For example, configure.ac could contain:

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

and then a Makefile.in could contain:

@host_frag@

The string variable is passed to m4_pattern_allow (see Forbidden Patterns).

Running configure in varying environments can be extremely dangerous. If for instance the user runs ‘CC=bizarre-cc ./configure’, then the cache, config.h, and many other output files depend upon bizarre-cc being the C compiler. If for some reason the user runs ./configure again, or if it is run via ‘./config.status --recheck’, (See Automatic Remaking and config.status Invocation), then the configuration can be inconsistent, composed of results depending upon two different compilers.

Environment variables that affect this situation, such as ‘CC’ above, are called precious variables, and can be declared as such by AC_ARG_VAR.

Macro: AC_ARG_VAR (variable, description)

Declare variable is a precious variable, and include its description in the variable section of ‘./configure --help’.

Being precious means that

• - variable is substituted via AC_SUBST.
• - The value of variable when configure was launched is saved in the cache, including if it was not specified on the command line but via the environment. Indeed, while configure can notice the definition of CC in ‘./configure CC=bizarre-cc’, it is impossible to notice it in ‘CC=bizarre-cc ./configure’, which, unfortunately, is what most users do.

  We emphasize that it is the initial value of variable which is saved, not that found during the execution of configure. Indeed, specifying ‘./configure FOO=foo’ and letting ‘./configure’ guess that FOO is foo can be two different things.

• - variable is checked for consistency between two configure runs. For instance:

  $ ./configure --silent --config-cache
  $ CC=cc ./configure --silent --config-cache
  configure: error: 'CC' was not set in the previous run
  configure: error: changes in the environment can compromise \
  the build
  configure: error: run 'make distclean' and/or \
  'rm config.cache' and start over
  

  and similarly if the variable is unset, or if its content is changed. If the content has white space changes only, then the error is degraded to a warning only, but the old value is reused.

• - variable is kept during automatic reconfiguration (see config.status Invocation) as if it had been passed as a command line argument, including when no cache is used:

  $ CC=/usr/bin/cc ./configure var=raboof --silent
  $ ./config.status --recheck
  running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
    CC=/usr/bin/cc  --no-create --no-recursion