FYI: AC_CONFIG_{FILES,HEADERS,LINKS} and shell variables

[Alexandre Duret-Lutz]

I'm installing this on HEAD.

2005-01-01  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Requirements) <AC_CONFIG_FILES>: Discuss
        specifications with shell variables.
        (Optional) <AC_CONFIG_HEADERS, AC_CONFIG_LINKS>: Point to
        AC_CONFIG_FILES for this explanation.
        * automake.in (substitute_ac_subst_variables_worker,
        substitute_ac_subst_variables): Mew functions.
        (rewrite_inputs_into_dependencies): Use substitute_ac_subst_variables
        to ignore dependencies that contain unAC_SUBSTed shell variables.
        (handle_configure): Likewise, do not output rules for
        AC_CONFIG_HEADERS, AC_CONFIG_FILES, and AC_CONFIG_LINKS targets that
        unAC_SUBSTed contain shell variables.
        * tests/autohdr4.test: Use an AC_SUBST variable in a specification.
        * tests/output11.test, tests/output12.test: New files.
        * tests/Makefile.am (TESTS): Add output11.test and output12.test.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.293
diff -u -r1.293 NEWS
--- NEWS        1 Jan 2005 12:28:44 -0000       1.293
+++ NEWS        1 Jan 2005 17:12:47 -0000
@@ -36,6 +36,15 @@
     flavors, including optional formats such as dvi, ps, or info even
     when `no-installinfo' is used.)
 
+  - Automake no longer complains if input files for AC_CONFIG_FILES
+    are specified using shell variables.
+
+  - clean, distribution, or rebuild rules are normally disabled for
+    inputs and outputs of AC_CONFIG_FILES, AC_CONFIG_HEADERS, and
+    AC_CONFIG_LINK specified using shell variable.  However if these
+    variables are used as ${VAR}, and AC_SUBSTed, then Automake will
+    be able to output rules anyway.
+    (See the Automake documentation for AC_CONFIG_FILES.)
 
 New in 1.9:
 
Index: automake.in
===================================================================
RCS file: /cvs/automake/automake/automake.in,v
retrieving revision 1.1595
diff -u -r1.1595 automake.in
--- automake.in 1 Jan 2005 12:28:44 -0000       1.1595
+++ automake.in 1 Jan 2005 17:12:48 -0000
@@ -3734,6 +3734,25 @@
 }
 
 
+# Helper function for substitute_ac_subst_variables.
+sub substitute_ac_subst_variables_worker($)
+{
+  my ($token) = @_;
+  return "address@hidden@" if var $token;
+  return "\${$token\}";
+}
+
+# substitute_ac_subst_variables ($TEXT)
+# -------------------------------------
+# Replace any occurence of ${FOO} in $TEXT by @FOO@ if FOO is an AC_SUBST
+# variable.
+sub substitute_ac_subst_variables ($)
+{
+  my ($text) = @_;
+  $text =~ s/\${([^ \t=:+{}]+)}/&substitute_ac_subst_variables_worker ($1)/ge;
+  return $text;
+}
+
 # @DEPENDENCIES
 # &prepend_srcdir (@INPUTS)
 # -------------------------
@@ -3775,6 +3794,9 @@
 
   for my $i (@inputs)
     {
+      # We cannot create dependencies on shell variables.
+      next if (substitute_ac_subst_variables $i) =~ /\$/;
+
       if (exists $ac_config_files_location{$i})
        {
          my $di = dirname $i;
@@ -3795,7 +3817,7 @@
        {
          msg ('error', $ac_config_files_location{$file},
               "required file `$i' not found")
-           unless exists $output_files{$i} || -f $i;
+           unless $i =~ /\$/ || exists $output_files{$i} || -f $i;
          ($i) = prepend_srcdir ($i);
          push_dist_common ($i);
        }
@@ -3894,7 +3916,10 @@
          # This will also distribute all inputs.
          @ins = rewrite_inputs_into_dependencies ($config_h_path, @ins);
 
-         # Header defined and in this directory.
+         # Cannot define rebuild rules for filenames with shell variables.
+         next if (substitute_ac_subst_variables $config_h_path) =~ /\$/;
+
+         # Header defined in this directory.
          my @files;
          if (-f $config_h_path . '.top')
            {
@@ -4033,6 +4058,9 @@
 
       my @rewritten_inputs = rewrite_inputs_into_dependencies ($file, @inputs);
 
+      # Cannot output rules for shell variables.
+      next if (substitute_ac_subst_variables $local) =~ /\$/;
+
       $output_rules .= ($local . ': '
                        . '$(top_builddir)/config.status '
                        . "@rewritten_inputs\n"
@@ -4055,7 +4083,7 @@
       my $where = $ac_config_files_location{$link};
 
       # Skip destinations that contain shell variables.
-      if ($link !~ /\$/)
+      if ((substitute_ac_subst_variables $link) !~ /\$/)
        {
          # We skip links that aren't in this directory.  However, if
          # the link's directory does not have a Makefile, and we are
@@ -4078,7 +4106,7 @@
        }
 
       # Do not process sources that contain shell variables.
-      if ($file !~ /\$/)
+      if ((substitute_ac_subst_variables $file) !~ /\$/)
        {
          my $fd = dirname ($file);
 
Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.82
diff -u -r1.82 automake.texi
--- doc/automake.texi   30 Dec 2004 23:10:50 -0000      1.82
+++ doc/automake.texi   1 Jan 2005 17:12:50 -0000
@@ -14,7 +14,7 @@
 Makefiles from template files.
 
 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004 Free Software Foundation, Inc.
+2003, 2004, 2005 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -1301,7 +1301,93 @@
 file exists.  If no such file exists the output file is not considered
 to be Automake generated.
 
-Files created by @code{AC_CONFIG_FILES} are removed by @code{make distclean}.
+Files created by @code{AC_CONFIG_FILES}, be they Automake
address@hidden or not, are all removed by @code{make distclean}.
+Their inputs are automatically distributed, except for input that
+turns out the be the outputs of prior @code{AC_CONFIG_FILES} commands.
+Finally, rebuild rules are generated in the Automake @file{Makefile}
+in the subdirectory of the output file, if there is one, or in the
+top-level @file{Makefile} otherwise.
+
+The above machinery (cleaning, distributing, and rebuilding) works
+fine only if the @code{AC_CONFIG_FILES} specifications contain only
+literals.  If part of the specification uses shell variables,
address@hidden will not be able to fulfil this setup, and you will
+have to complete the missing bits by hand.  For instance on
+
address@hidden
+file=input
address@hidden
+AC_CONFIG_FILES([output:$file],, [file=$file])
address@hidden example
+
address@hidden
address@hidden will output rules to clean @file{output}, and
+rebuild it.  However the rebuild rule will not depend on @file{input},
+and this file will not be distributed either.  (You must add
address@hidden = input} to your @file{Makefile} if @file{input} is a
+source file.)
+
+Similarly
+
address@hidden
+file=output
+file2=out:in
address@hidden
+AC_CONFIG_FILES([$file:input],, [file=$file])
+AC_CONFIG_FILES([$file2],, [file2=$file2])
address@hidden example
+
address@hidden
+will only cause @file{input} to be distributed.  No file will be
+cleaned automatically (add @code{DISTCLEANFILES = output out}
+yourself), and no rebuild rule will be output.
+
+Obviously @command{automake} cannot guess what value @code{$file} is
+going to hold later when @file{configure} is run, and it cannot use
+the shell variable @code{$file} in a @file{Makefile}.  However, if you
+make reference to @code{$file} as @address@hidden@}} (i.e., in a way
+that is compatible with @command{make}'s syntax) and furthermore use
address@hidden to ensure that @address@hidden@}} is meaningful in a
address@hidden, then @command{automake} will be able to use
address@hidden@address@hidden to generate all these rules.  For instance here is
+how the Automake package itself generates versioned scripts for its
+test suite:
+
address@hidden
+AC_SUBST([APIVERSION], @dots{})
address@hidden
+AC_CONFIG_FILES([tests/address@hidden@}:tests/aclocal.in],
+                [chmod +x tests/address@hidden@}],
+                [APIVERSION=$APIVERSION])
+AC_CONFIG_FILES([tests/address@hidden@}:tests/automake.in],
+                [chmod +x tests/address@hidden@}])
address@hidden example
+
address@hidden
+Here cleaning, distributing, and rebuilding are done automatically,
+because @address@hidden@}} is know at @code{make}-time.
+
+Note that you should not use shell variables to declare
address@hidden files for which @command{automake} must create
address@hidden  Even @code{AC_SUBST} does not help here, because
address@hidden needs to know the filename at run-time in order to
+check whether @file{Makefile.am} exists.  (In the very hairy case that
+your setup requires such use of variables, you will have to tell
+Automake which @file{Makefile.in}s to generate on the command-line.)
+
+To summarize:
address@hidden @bullet
address@hidden
+Use literals for @file{Makefile}s, and for other files whenever possible.
address@hidden
+Use @code{$file} (or @address@hidden@}} without @code{AC_SUBST([file])})
+for files that @command{automake} should ignore.
address@hidden
+Use @address@hidden@}} and @code{AC_SUBST([file])} for files
+that @command{automake} should not ignore.
address@hidden itemize
+
 @end table
 
 
@@ -1322,10 +1408,18 @@
 of Automake required the use of @code{AM_CONFIG_HEADER}
 (@pxref{Macros}); this is no longer the case today.
 
+As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
+specification using shell variables will be ignored as far as
+cleaning, distributing, and rebuilding is concerned.
+
 @item AC_CONFIG_LINKS
-Automake will generate rules to remove @file{configure} generated links on
address@hidden distclean} and to distribute named source files as part of
address@hidden dist}.
+Automake will generate rules to remove @file{configure} generated
+links on @code{make distclean} and to distribute named source files as
+part of @code{make dist}.
+
+As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
+specification using shell variables will be ignored as far as cleaning
+and distributing is concerned.  (There is no rebuild rules for links.)
 
 @item AC_CONFIG_AUX_DIR
 Automake will look for various helper scripts, such as
Index: tests/Makefile.am
===================================================================
RCS file: /cvs/automake/automake/tests/Makefile.am,v
retrieving revision 1.576
diff -u -r1.576 Makefile.am
--- tests/Makefile.am   9 Dec 2004 22:07:45 -0000       1.576
+++ tests/Makefile.am   1 Jan 2005 17:12:51 -0000
@@ -370,6 +370,8 @@
 output8.test \
 output9.test \
 output10.test \
+output11.test \
+output12.test \
 overrid.test \
 parse.test \
 percent.test \
Index: tests/autohdr4.test
===================================================================
RCS file: /cvs/automake/automake/tests/autohdr4.test,v
retrieving revision 1.1
diff -u -r1.1 autohdr4.test
--- tests/autohdr4.test 26 Oct 2003 21:20:11 -0000      1.1
+++ tests/autohdr4.test 1 Jan 2005 17:12:51 -0000
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Copyright (C) 2003  Free Software Foundation, Inc.
+# Copyright (C) 2003, 2005  Free Software Foundation, Inc.
 #
 # This file is part of GNU Automake.
 #
@@ -26,9 +26,11 @@
 
 set -e
 
-cat >>configure.in <<EOF
+cat >>configure.in <<'EOF'
 AC_PROG_CC
-AC_CONFIG_HEADERS([defs.h config.h:sub1/config.top:sub2/config.bot])
+AC_SUBST([BOT], [bot])
+AC_CONFIG_HEADERS([defs.h config.h:sub1/config.top:sub2/config.${BOT}],,
+                  [BOT=$BOT])
 AC_CONFIG_FILES([sub3/Makefile])
 AC_OUTPUT
 EOF
Index: tests/output11.test
===================================================================
RCS file: tests/output11.test
diff -N tests/output11.test
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ tests/output11.test 1 Jan 2005 17:12:51 -0000
@@ -0,0 +1,69 @@
+#! /bin/sh
+# Copyright (C) 2005  Free Software Foundation, Inc.
+#
+# This file is part of GNU Automake.
+#
+# GNU Automake is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# GNU Automake is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Automake; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+# Make sure an AC_CONFIG_FILES ignore filenames with shell variables.
+
+. ./defs || exit 1
+
+set -e
+
+cat >> configure.in << \END
+AC_SUBST([FOO], [foo])
+file1=this.in
+echo @FOO@ >$file1
+file2=that
+file3=mumble
+file4=foo
+AC_CONFIG_FILES([this:$file1],, [file1=$file1])
+AC_CONFIG_FILES([sub/this:$file1])
+AC_CONFIG_FILES([${file2}:this],, [file2=$file2])
+AC_CONFIG_FILES([$file3],, [file3=$file3])
+AC_CONFIG_FILES([$file4:foo.in],, [file4=$file4])
+AC_CONFIG_FILES([sub/Makefile])
+AC_OUTPUT
+END
+
+mkdir sub
+
+cat >Makefile.am <<\EOF
+SUBDIRS = sub
+EXTRA_DIST = mumble.in
+DISTCLEANFILES = this.in that mumble foo
+dist-hook:
+       test -f $(distdir)/foo.in
+       test ! -f $(distdir)/this
+EOF
+
+echo @FOO@ >mumble.in
+echo @FOO@ >foo.in
+: >sub/Makefile.am
+
+$ACLOCAL
+$AUTOCONF
+$AUTOMAKE
+
+$FGREP ' $file' Makefile.in sub/Makefile.in && exit 1
+
+./configure
+$MAKE distcheck
+cd sub
+rm this
+$MAKE this
+grep foo this
Index: tests/output12.test
===================================================================
RCS file: tests/output12.test
diff -N tests/output12.test
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ tests/output12.test 1 Jan 2005 17:12:51 -0000
@@ -0,0 +1,66 @@
+#! /bin/sh
+# Copyright (C) 2005  Free Software Foundation, Inc.
+#
+# This file is part of GNU Automake.
+#
+# GNU Automake is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# GNU Automake is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Automake; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+# Make sure an AC_CONFIG_FILES process filenames with AC_SUBST variables.
+
+. ./defs || exit 1
+
+set -e
+
+cat >> configure.in << \END
+AC_SUBST([FOO], [foo])
+AC_SUBST([file1], [this.in])
+echo @FOO@ >$file1
+AC_SUBST([file2], [that])
+AC_SUBST([file3], [mumble])
+AC_SUBST([file4], [foo])
+AC_CONFIG_FILES([this:$file1],, [file1=$file1])
+AC_CONFIG_FILES([sub/this:$file1])
+AC_CONFIG_FILES([${file2}:this],, [file2=$file2])
+AC_CONFIG_FILES([${file3}],, [file3=$file3])
+AC_CONFIG_FILES([${file4}:foo.in],, [file4=$file4])
+AC_CONFIG_FILES([sub/Makefile])
+AC_OUTPUT
+END
+
+mkdir sub
+
+cat >Makefile.am <<\EOF
+SUBDIRS = sub
+DISTCLEANFILES = $(file1)
+dist-hook:
+       test -f $(distdir)/foo.in
+       test ! -f $(distdir)/this
+EOF
+
+echo @FOO@ >mumble.in
+echo @FOO@ >foo.in
+: >sub/Makefile.am
+
+$ACLOCAL
+$AUTOCONF
+$AUTOMAKE
+
+./configure
+$MAKE distcheck
+cd sub
+rm this
+$MAKE this
+grep foo this
-- 
Alexandre Duret-Lutz