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 (autoconf)Output section `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 Automake generated.

Files created by AC_CONFIG_FILES, be they Automake ‘Makefile’s or not, are all removed by ‘make distclean’. Their inputs are automatically distributed, except for inputs that turn out the be outputs 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’ 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 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.)

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.