6.1 Configuration requirements

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 section Autoconf macros supplied with Automake).

Here are the other macros that Automake requires but which are not run by AM_INIT_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 Creating Output Files in The Autoconf Manual). 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 ‘Makefile’s 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.in’s 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 section Other things Automake recognizes).

To summarize:

• Use literals for ‘Makefile’s, 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.

This document was generated on January 25, 2014 using texi2html 5.0.