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