Info Catalog automake-1.16: configure automake-1.16: Optional

automake-1.16: Requirements

 
 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 (⇒Macros).
 
    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 (⇒
      Creating Output Files (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 ‘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’ (⇒Optional).
 
      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.
 

Info Catalog automake-1.16: configure automake-1.16: Optional