automake: Requirements
1
1 6.1 Configuration requirements
1 ==============================
1
1 The one real requirement of Automake is that your ‘configure.ac’ call
1 ‘AM_INIT_AUTOMAKE’. This macro does several things that are required
1 for proper Automake operation (⇒Macros).
1
1 Here are the other macros that Automake requires but which are not
1 run by ‘AM_INIT_AUTOMAKE’:
1
1 ‘AC_CONFIG_FILES’
1 ‘AC_OUTPUT’
1 These two macros are usually invoked as follows near the end of
1 ‘configure.ac’.
1
1 ...
1 AC_CONFIG_FILES([
1 Makefile
1 doc/Makefile
1 src/Makefile
1 src/lib/Makefile
1 ...
1 ])
1 AC_OUTPUT
1
11 Automake uses these to determine which files to create (⇒
Creating Output Files (autoconf)Output.). A listed file is
1 considered to be an Automake generated ‘Makefile’ if there exists a
1 file with the same name and the ‘.am’ extension appended.
1 Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to
1 generate ‘foo/Makefile.in’ if ‘foo/Makefile.am’ exists.
1
1 When using ‘AC_CONFIG_FILES’ with multiple input files, as in
1
1 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
1
1 ‘automake’ will generate the first ‘.in’ input file for which a
1 ‘.am’ file exists. If no such file exists the output file is not
1 considered to be generated by Automake.
1
1 Files created by ‘AC_CONFIG_FILES’, be they Automake ‘Makefile’s or
1 not, are all removed by ‘make distclean’. Their inputs are
1 automatically distributed, unless they are the output of prior
1 ‘AC_CONFIG_FILES’ commands. Finally, rebuild rules are generated
1 in the Automake ‘Makefile’ existing in the subdirectory of the
1 output file, if there is one, or in the top-level ‘Makefile’
1 otherwise.
1
1 The above machinery (cleaning, distributing, and rebuilding) works
1 fine if the ‘AC_CONFIG_FILES’ specifications contain only literals.
1 If part of the specification uses shell variables, ‘automake’ will
1 not be able to fulfill this setup, and you will have to complete
1 the missing bits by hand. For instance, on
1
1 file=input
1 ...
1 AC_CONFIG_FILES([output:$file],, [file=$file])
1
1 ‘automake’ will output rules to clean ‘output’, and rebuild it.
1 However the rebuild rule will not depend on ‘input’, and this file
1 will not be distributed either. (You must add ‘EXTRA_DIST = input’
1 to your ‘Makefile.am’ if ‘input’ is a source file.)
1
1 Similarly
1
1 file=output
1 file2=out:in
1 ...
1 AC_CONFIG_FILES([$file:input],, [file=$file])
1 AC_CONFIG_FILES([$file2],, [file2=$file2])
1
1 will only cause ‘input’ to be distributed. No file will be cleaned
1 automatically (add ‘DISTCLEANFILES = output out’ yourself), and no
1 rebuild rule will be output.
1
1 Obviously ‘automake’ cannot guess what value ‘$file’ is going to
1 hold later when ‘configure’ is run, and it cannot use the shell
1 variable ‘$file’ in a ‘Makefile’. However, if you make reference
1 to ‘$file’ as ‘${file}’ (i.e., in a way that is compatible with
1 ‘make’’s syntax) and furthermore use ‘AC_SUBST’ to ensure that
1 ‘${file}’ is meaningful in a ‘Makefile’, then ‘automake’ will be
1 able to use ‘${file}’ to generate all of these rules. For
1 instance, here is how the Automake package itself generates
1 versioned scripts for its test suite:
1
1 AC_SUBST([APIVERSION], ...)
1 ...
1 AC_CONFIG_FILES(
1 [tests/aclocal-${APIVERSION}:tests/aclocal.in],
1 [chmod +x tests/aclocal-${APIVERSION}],
1 [APIVERSION=$APIVERSION])
1 AC_CONFIG_FILES(
1 [tests/automake-${APIVERSION}:tests/automake.in],
1 [chmod +x tests/automake-${APIVERSION}])
1
1 Here cleaning, distributing, and rebuilding are done automatically,
1 because ‘${APIVERSION}’ is known at ‘make’-time.
1
1 Note that you should not use shell variables to declare ‘Makefile’
1 files for which ‘automake’ must create ‘Makefile.in’. Even
1 ‘AC_SUBST’ does not help here, because ‘automake’ needs to know the
1 file name when it runs in order to check whether ‘Makefile.am’
1 exists. (In the very hairy case that your setup requires such use
1 of variables, you will have to tell Automake which ‘Makefile.in’s
1 to generate on the command-line.)
1
1 It is possible to let ‘automake’ emit conditional rules for
1 ‘AC_CONFIG_FILES’ with the help of ‘AM_COND_IF’ (⇒Optional).
1
1 To summarize:
1 • Use literals for ‘Makefile’s, and for other files whenever
1 possible.
1 • Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for
1 files that ‘automake’ should ignore.
1 • Use ‘${file}’ and ‘AC_SUBST([file])’ for files that ‘automake’
1 should not ignore.
1