5.2.4 Requirements of automake

Every time Automake is run it calls Autoconf to “trace” configure.ac. This way it can recognize the use of certain macros and tailor the generated Makefile.in appropriately.

The one real requirement of Automake is that your configure.ac call AM_INIT_AUTOMAKE. This macro does several things that are required for proper Automake operation (see Macros supplied with Automake).

Here are the other macros required by Automake:

AC_CONFIG_FILES

AC_OUTPUT

These two macros are usually invoked as follows near the end of configure.ac.

…
AC_CONFIG_FILES([
  Makefile
  doc/Makefile
  src/Makefile
  src/lib/Makefile
  …
])
AC_OUTPUT

Automake uses these to determine which files to create (see Autoconf output). A listed file is considered to be an Automake generated Makefile if there exists a file with the same name and the .am extension appended. Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to generate foo/Makefile.in if foo/Makefile.am exists.

When using AC_CONFIG_FILES with multiple input files, as in

AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])

automake will generate the first .in input file for which a .am file exists. If no such file exists the output file is not considered to be generated by Automake.

Files created by AC_CONFIG_FILES, be they Automake Makefiles or not, are all removed by ‘make distclean’. Their inputs are automatically distributed, unless they are the output of prior AC_CONFIG_FILES commands. Finally, rebuild rules are generated in the Automake Makefile existing in the subdirectory of the output file, if there is one, or in the top-level Makefile otherwise.

The above machinery (cleaning, distributing, and rebuilding) works fine if the AC_CONFIG_FILES specifications contain only literals. If part of the specification uses shell variables, automake will not be able to fulfill this setup, and you will have to complete the missing bits by hand. For instance, on

file=input
…
AC_CONFIG_FILES([output:$file],, [file=$file])

automake will output rules to clean output, and rebuild it. However the rebuild rule will not depend on input, and this file will not be distributed either. (You must add ‘EXTRA_DIST = input’ to your Makefile.am if input is a source file.)

Similarly

file=output
file2=out:in
…
AC_CONFIG_FILES([$file:input],, [file=$file])
AC_CONFIG_FILES([$file2],, [file2=$file2])

will only cause input to be distributed. No file will be cleaned automatically (add ‘DISTCLEANFILES = output out’ yourself), and no rebuild rule will be output.

Obviously automake cannot guess what value ‘$file’ is going to hold later when configure is run, and it cannot use the shell variable ‘$file’ in a Makefile. However, if you make reference to ‘$file’ as ‘${file}’ (i.e., in a way that is compatible with make’s syntax) and furthermore use AC_SUBST to ensure that ‘${file}’ is meaningful in a Makefile, then automake will be able to use ‘${file}’ to generate all of these rules. For instance, here is how the Automake package itself generates versioned scripts for its test suite:

AC_SUBST([APIVERSION], …)
…
AC_CONFIG_FILES(
  [tests/aclocal-${APIVERSION}:tests/aclocal.in],
  [chmod +x tests/aclocal-${APIVERSION}],
  [APIVERSION=$APIVERSION])
AC_CONFIG_FILES(
  [tests/automake-${APIVERSION}:tests/automake.in],
  [chmod +x tests/automake-${APIVERSION}])

Here cleaning, distributing, and rebuilding are done automatically, because ‘${APIVERSION}’ is known at make-time.

Note that you should not use shell variables to declare Makefile files for which automake must create Makefile.in. Even AC_SUBST does not help here, because automake needs to know the file name when it runs in order to check whether Makefile.am exists. (In the very hairy case that your setup requires such use of variables, you will have to tell Automake which Makefile.ins to generate on the command-line.)

It is possible to let automake emit conditional rules for AC_CONFIG_FILES with the help of AM_COND_IF (see Other macros Automake recognizes).

To summarize:

• Use literals for Makefiles, and for other files whenever possible.
• Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for files that automake should ignore.
• Use ‘${file}’ and ‘AC_SUBST([file])’ for files that automake should not ignore.