missing: do not touch timestamps; only warn for out-of-date files

Before this change, the missing script had a twofold role:

  - it warned the user if some required maintainer tools was missing,
    or too old;

  - in such a case, it tried to "fix" the timestamp of the files that
    should have been rebuilt by that tool (without actually updating
    the file contents, of course), to allow the build to continue.

The second capability used to be quite useful in the days when most
projects committed files generated by maintainer-only tools in their
VCS repository (today the trend is not to keep such generated files
VCS-committed anymore).  In such a setup, the "timestamp-fixing"
capability of 'missing' was quite useful, in that it allowed users
lacking some required maintainer tool to build from a VCS checkout
in the face of skewed timestamps (as could have been caused by
"cvs update" or "git checkout").

But then, when the automatic remake rules kicked in due to the
generated files being *actually out-of-date* (e.g., because the user
had modified 'configure.ac' but lacked a modern-enough autoconf to
rebuild it), that behaviour of 'missing' caused the same problem that
plagued AM_MAINTAINER_MODE; i.e., the user would get non-dependable
builds and inconsistent statuses of the build tree -- changes to
source files don't reflect on generated files, and this can be very
confusing and cause hard-to-spot errors).

So we now believe that the best approach to deal with timestamp-related
issues is not to have 'missing' to "automagically" try to resolve
them (with all the risk and brittleness entailed), but rather to
suggest those projects still keeping generated files committed in their
VCS to provide a proper (say) 'fix-timestamp.sh' script that touches
the timestamp of the checked-out files, to ensure no spurious rebuild
will be triggered.  As a bonus, such a script can be more aware of the
particularities, nooks and corner cases of a project, and thus more
reliable than the old 'missing' script.

An example of this approach is offered by GNU awk (release 4.0.1, Git
tag 'gawk-4.0.1', commit b85b04e8).  The GNU awk maintainers commit
the Autotools-generated files (configure, Makefile.in, etc.) and other
generated in the project's Git repository, but offer a useful script
'bootstrap.sh' that fixes the timestamps of those files, to ensure no
useless remake is triggered in a freshly cloned repository:

    #! /bin/sh
    # bootstrap.sh --- touch relevant files to avoid out-of-date issues
    #                  in Git sandboxes
    touch aclocal.m4
    find awklib -type f -print | xargs touch
    sleep 1
    touch configure
    sleep 2
    touch configh.in
    sleep 1
    touch test/Maketests
    find . -name Makefile.in -print | xargs touch
    touch doc/*.info
    touch po/*.gmo
    touch po/stamp-po
    touch awkgram.c
    touch command.c
    touch version.c

A similar, simplified script is also reported as an example in the
manual.

* NEWS: Update.
* doc/automake.texi (Auxiliary Programs, maintainer-mod): Update.
(CVS): Do not suggest that 'missing' can "automagically" fix botched
timestamp due to a "cvs update"; this isn't true anymore.  Give an
example of a custom 'fix-timestamp.sh' script that can be used to
obtain the same effect (in a slightly more laborious but also more
explicit and less brittle way).  Fix some minor typos and improper
wordings while we are at it.
* lib/missing: Basically rewritten to implement the new semantics.
As a side effect (one of the several), the '--run' option is no more
required nor recognized.
* m4/missing.m4 (AM_MISSING_HAS_RUN): Enhance the test on '$MISSING'
to ensure it actually provides the new semantics (by trying the new
"witness" option '--is-lightweight').
* lib/am/distdir.am (distdir): No need anymore to check for "bad"
distributed man pages that were actually dummy stubs generated by
the 'missing' script.
* t/missing4.sh: Rename ...
* t/remake-aclocal-version-mismatch.sh: ... like this.
* t/missing2.sh: Rename ...
* t/missing-version-mismatch.sh: ... like this, and adjust to the
new semantics.
* t/missing3.sh: Adjust to the new semantics.
* t/man4.sh: Remove as obsolete.
* t/missing.sh: Likewise.
* t/missing5.sh: Likewise.
* t/txinfo30.sh: Likewise.
* t/man6.sh: Adjust grepping checks.
* t/remake6.sh: Likewise.
* t/list-of-tests.mk: Adjust.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

11 files changed, 51 insertions, 366 deletions

diff --git a/t/missing6.sh b/t/aclocal-autoconf-version-check.sh
index 8173f818a..8173f818a 100755
--- a/t/missing6.sh
+++ b/t/aclocal-autoconf-version-check.sh
diff --git a/t/list-of-tests.mk b/t/list-of-tests.mk
index b80c07155..4eecb3e3c 100644
--- a/t/list-of-tests.mk
+++ b/t/list-of-tests.mk
@@ -109,6 +109,7 @@ t/aclocal-install-fail.sh \
 t/aclocal-install-mkdir.sh \
 t/aclocal-no-install-no-mkdir.sh \
 t/aclocal-verbose-install.sh \
+t/aclocal-autoconf-version-check.sh \
 t/ac-output-old.tap \
 t/acsilent.sh \
 t/acsubst.sh \
@@ -656,7 +657,6 @@ t/makevars.sh \
 t/man.sh \
 t/man2.sh \
 t/man3.sh \
-t/man4.sh \
 t/man5.sh \
 t/man6.sh \
 t/man7.sh \
@@ -667,12 +667,8 @@ t/mdate3.sh \
 t/mdate4.sh \
 t/mdate5.sh \
 t/mdate6.sh \
-t/missing.sh \
-t/missing2.sh \
+t/missing-version-mismatch.sh \
 t/missing3.sh \
-t/missing4.sh \
-t/missing5.sh \
-t/missing6.sh \
 t/missing-auxfile-stops-makefiles-creation.sh \
 t/mkinstall.sh \
 t/mkinst2.sh \
@@ -931,6 +927,7 @@ t/remake-deleted-am-2.sh \
 t/remake-deleted-am-subdir.sh \
 t/remake-deleted-am.sh \
 t/remake-renamed-am.sh \
+t/remake-aclocal-version-mismatch.sh \
 t/pr8365-remake-timing.sh \
 t/req.sh \
 t/reqd.sh \
@@ -1177,7 +1174,6 @@ t/txinfo26.sh \
 t/txinfo27.sh \
 t/txinfo28.sh \
 t/txinfo29.sh \
-t/txinfo30.sh \
 t/txinfo31.sh \
 t/txinfo32.sh \
 t/txinfo33.sh \
diff --git a/t/man4.sh b/t/man4.sh
deleted file mode 100755
index c7333b9c2..000000000
--- a/t/man4.sh
+++ /dev/null
@@ -1,105 +0,0 @@
-#! /bin/sh
-# Copyright (C) 2008-2012 Free Software Foundation, Inc.
-#
-# This program 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.
-#
-# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Ensure 'make dist' fails when help2man replacement man pages are created.
-#
-# The assumption here is the following: if the developer uses help2man to
-# generate man pages from --help output, then these man pages may not be
-# stored in VCS.  However, they should be distributed, so that the end user
-# that receives the tarball doesn't have to install help2man.  If they are
-# not distributed, then the developer should make help2man a prerequisite
-# to building the package from a tarball, e.g., with a configure check for
-# help2man that errors out if it is unavailable.  In both cases it is
-# sufficient to check only distributed man pages.
-#
-# Idea of this whole shenanigan is to allow somebody to check out sources from
-# a VCS and build and install them without needing help2man installed.  The
-# installed man pages will be bogus in this case.  Typically, this happens
-# when developers ask users to try out a fix from VCS; the developers themselves
-# will usually have help2man installed (or should install it).
-
-. ./defs || Exit 1
-
-cat > Makefile.am << 'END'
-dist_man_MANS = $(srcdir)/foo.1 bar.1
-dist_bin_SCRIPTS = foo bar
-$(srcdir)/foo.1:
-	$(HELP2MAN) --output=$@ $(srcdir)/foo
-bar.1:
-	$(HELP2MAN) --output=$(srcdir)/bar.1 $(srcdir)/bar
-END
-
-cat >>configure.ac <<'END'
-AM_MISSING_PROG([HELP2MAN], [help2man])
-AC_OUTPUT
-END
-
-cat > foo <<'END'
-#! /bin/sh
-while test $# -gt 0; do
-  case $1 in
-    -h | --help) echo "usage: $0 [OPTIONS]..."; exit 0;;
-    -v | --version) echo "$0 1.0"; exit 0;;
-  esac
-  shift
-done
-END
-cp foo bar
-chmod +x foo bar
-
-mkdir bin
-cat > bin/help2man <<'END'
-#! /bin/sh
-# Fake help2man script that lets 'missing' think it is not installed.
-exit 127
-END
-chmod +x bin/help2man
-PATH=`pwd`/bin$PATH_SEPARATOR$PATH
-
-grep_error_messages()
-{
-  grep ' man pages contain.*missing help2man.* replacement text' stderr \
-   && grep 'install help2man' stderr \
-   && grep 'regenerate the man pages' stderr \
-   || Exit 1
-}
-
-$ACLOCAL
-$AUTOMAKE
-$AUTOCONF
-
-./configure
-$MAKE
-$MAKE dist 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep_error_messages
-$MAKE distcheck 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep_error_messages
-$MAKE distclean
-
-mkdir build
-cd build
-../configure
-$MAKE
-$MAKE dist 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep_error_messages
-$MAKE distcheck 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep_error_messages
-
-:
diff --git a/t/man6.sh b/t/man6.sh
index 1a7b26751..e3c5569bf 100755
--- a/t/man6.sh
+++ b/t/man6.sh
@@ -65,7 +65,7 @@ cd build
 
 ../configure
 # Sanity check.
-grep '^HELP2MAN *=.*/missing --run help2man' Makefile
+grep '^HELP2MAN *=.*/missing help2man' Makefile
 
 $MAKE
 $FGREP foobar ../foobar.1
@@ -84,7 +84,7 @@ rm -f *.1 # Remove leftover generated manpages.
 
 ./configure
 # Sanity check.
-grep '^HELP2MAN *=.*/missing --run help2man' Makefile
+grep '^HELP2MAN *=.*/missing help2man' Makefile
 
 $MAKE
 $FGREP foobar  foobar.1
diff --git a/t/missing2.sh b/t/missing-version-mismatch.sh
index 89e9a5daf..4a2910a04 100755
--- a/t/missing2.sh
+++ b/t/missing-version-mismatch.sh
@@ -16,43 +16,35 @@
 
 # Test missing with version mismatches.
 
+am_create_testdir=empty
 . ./defs || Exit 1
 
-cat >>configure.ac <<'EOF'
-m4_include([v.m4])
-AC_OUTPUT
-EOF
+get_shell_script missing
 
-: > v.m4
+do_check ()
+{
+  progname=$1; shift;
+  ./missing "$@" 2>stderr && { cat stderr >&2; Exit 1; }
+  cat stderr >&2
+  $FGREP "WARNING: '$progname' is probably too old." stderr
+}
 
-: > Makefile.am
+echo 'AC_INIT([x], [1.0]) AC_PREREQ([9999])' >> configure.ac
 
-get_shell_script missing
+do_check autoconf               $AUTOCONF
+do_check autoheader             $AUTOHEADER
+do_check aclocal-$APIVERSION    $am_original_ACLOCAL
+
+cat > configure.ac << 'END'
+AC_INIT([x], [0])
+AM_INIT_AUTOMAKE
+AC_CONFIG_FILES([Makefile])
+END
 
+echo AUTOMAKE_OPTIONS = 9999.9999 > Makefile.am
 $ACLOCAL
-$AUTOCONF
-$AUTOMAKE --add-missing
-
-# See missing.test for explanations about this.
-MYAUTOCONF="./missing --run $AUTOCONF"
-unset AUTOCONF
-
-./configure AUTOCONF="$MYAUTOCONF"
-
-$MAKE
-$sleep
-# Hopefully the install version of Autoconf cannot compete with this one...
-echo 'AC_PREREQ(9999)' > v.m4
-$MAKE distdir
-
-# Run again, but without missing, to ensure that timestamps were updated.
-export AUTOMAKE ACLOCAL
-./configure AUTOCONF="$MYAUTOCONF"
-$MAKE
-
-# Make sure $MAKE fail when timestamps aren't updated and missing is not used.
-$sleep
-touch v.m4
-$MAKE && Exit 1
+: > install-sh
+# FIXME: this doesn't work due to a bug in automake (not 'missing').
+#do_check automake-$APIVERSION  $am_original_AUTOMAKE
 
 :
diff --git a/t/missing.sh b/t/missing.sh
deleted file mode 100755
index 473d0412c..000000000
--- a/t/missing.sh
+++ /dev/null
@@ -1,66 +0,0 @@
-#! /bin/sh
-# Copyright (C) 2003-2012 Free Software Foundation, Inc.
-#
-# This program 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.
-#
-# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Test missing with version mismatches.
-
-. ./defs || Exit 1
-
-cat >>configure.ac <<'EOF'
-AC_OUTPUT
-EOF
-
-: > Makefile.am
-
-get_shell_script missing
-
-$ACLOCAL
-$AUTOCONF
-$AUTOMAKE --add-missing
-
-# Make sure we do use missing, even if the user exported AUTOCONF.
-# (We cannot export this new value, because it would be used by Automake
-# when tracing, and missing is no good for this.)
-MYAUTOCONF="./missing --run $AUTOCONF"
-unset AUTOCONF
-
-./configure AUTOCONF="$MYAUTOCONF"
-$MAKE
-$sleep
-# Hopefully the install version of Autoconf cannot compete with this one...
-echo 'AC_PREREQ(9999)' >> aclocal.m4
-$MAKE distdir
-
-# Try version number suffixes if we can add them safely.
-case $MYAUTOCONF in *autoconf)
-  ./configure AUTOCONF="${MYAUTOCONF}6789"
-  $MAKE
-  $sleep
-  # Hopefully the install version of Autoconf cannot compete with this one...
-  echo 'AC_PREREQ(9999)' >> aclocal.m4
-  $MAKE distdir
-esac
-
-# Run again, but without missing, to ensure that timestamps were updated.
-export AUTOMAKE ACLOCAL
-./configure AUTOCONF="$MYAUTOCONF"
-$MAKE
-
-# Make sure $MAKE fails when timestamps aren't updated and missing is not used.
-$sleep
-touch aclocal.m4
-$MAKE && Exit 1
-
-:
diff --git a/t/missing3.sh b/t/missing3.sh
index a26f954c9..e8641da18 100755
--- a/t/missing3.sh
+++ b/t/missing3.sh
@@ -23,31 +23,26 @@ get_shell_script missing
 
 # b7cb8259 assumed not to exist.
 
-./missing b7cb8259 --version 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep . stderr && Exit 1
-./missing b7cb8259 --grep 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep WARNING stderr
-
-./missing --run b7cb8259 --version && Exit 1
-./missing --run b7cb8259 --grep 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep WARNING stderr
+run_cmd ()
+{
+  st=0; "$@" >stdout 2>stderr || st=$?
+  cat stdout
+  cat stderr >&2
+  return $st
+}
+
+./missing b7cb8259 --version && Exit 1
+grep WARNING stderr && Exit 1
+run_cmd ./missing b7cb8259 --grep && Exit 1
+grep 'WARNING:.*missing on your system' stderr
 
 # missing itself it known to exist :)
 
-./missing ./missing --version 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep . stderr && Exit 1
-./missing ./missing --grep 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep WARNING stderr
-
-./missing --run ./missing --version 2>stderr || { cat stderr >&2; Exit 1; }
-cat stderr >&2
-grep . stderr && Exit 1
-./missing --run ./missing --grep 2>stderr && { cat stderr >&2; Exit 1; }
-cat stderr >&2
+run_cmd ./missing ./missing --version || Exit 1
+grep 'missing .*(GNU [aA]utomake)' stdout
+test -s stderr && Exit 1
+run_cmd ./missing ./missing --grep && Exit 1
 grep WARNING stderr && Exit 1
-grep Unknown stderr
+grep "missing:.* unknown '--grep'" stderr
+
+:
diff --git a/t/missing5.sh b/t/missing5.sh
deleted file mode 100755
index 80bba3691..000000000
--- a/t/missing5.sh
+++ /dev/null
@@ -1,64 +0,0 @@
-#! /bin/sh
-# Copyright (C) 2006-2012 Free Software Foundation, Inc.
-#
-# This program 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.
-#
-# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Test how well 'missing' finds output file names of various tools.
-# PR automake/483.
-
-am_create_testdir=empty
-. ./defs || Exit 1
-
-get_shell_script missing
-
-# These programs may be invoked by 'missing'.
-needed_tools='chmod find sed test touch'
-needed_tools_csep=`echo $needed_tools | sed 's/ /, /g'`
-
-cat >configure.ac <<EOF
-AC_INIT([missing4], [1.0])
-m4_foreach([tool], [$needed_tools_csep],
-	   [AC_PATH_PROG(tool, tool, [false])
-	    AC_CONFIG_FILES(tool, chmod +x tool)
-	   ])
-AC_OUTPUT
-EOF
-
-for tool in $needed_tools; do
-  unindent >$tool.in <<EOF
-    #! /bin/sh
-    exec @$tool@ "\$@"
-EOF
-done
-
-$AUTOCONF
-./configure
-
-echo output-file > output-file
-cp output-file my--output--file-o
-
-save_PATH=$PATH
-PATH=.
-export PATH
-missing --help
-missing --version
-for tool in autom4te help2man makeinfo; do
-  missing --run $tool -o my--output--file-o input
-  missing --run $tool --output my--output--file-o input
-done
-PATH=$save_PATH
-export PATH
-diff output-file my--output--file-o
-test ! -f ./--file-o
-test ! -f input
diff --git a/t/missing4.sh b/t/remake-aclocal-version-mismatch.sh
index 01321c349..01321c349 100755
--- a/t/missing4.sh
+++ b/t/remake-aclocal-version-mismatch.sh
diff --git a/t/remake6.sh b/t/remake6.sh
index c48c1b882..0fc7ead66 100755
--- a/t/remake6.sh
+++ b/t/remake6.sh
@@ -42,23 +42,23 @@ $MAKE
 rm -f Makefile.in
 $MAKE >stdout || { cat stdout; Exit 1; }
 cat stdout
-test `grep -c " --run " stdout` -eq 1
+test `grep -c "/missing " stdout` -eq 1
 
 rm -f sub/Makefile.in
 $MAKE >stdout || { cat stdout; Exit 1; }
 cat stdout
-test `grep -c " --run " stdout` -eq 1
+test `grep -c "/missing " stdout` -eq 1
 
 $sleep  # Let touched files appear newer.
 
 touch Makefile.am
 $MAKE >stdout || { cat stdout; Exit 1; }
 cat stdout
-test `grep -c " --run " stdout` -eq 1
+test `grep -c "/missing " stdout` -eq 1
 
 touch sub/Makefile.am
 $MAKE >stdout || { cat stdout; Exit 1; }
 cat stdout
-test `grep -c " --run " stdout` -eq 1
+test `grep -c "/missing " stdout` -eq 1
 
 :
diff --git a/t/txinfo30.sh b/t/txinfo30.sh
deleted file mode 100755
index 09ebd5e18..000000000
--- a/t/txinfo30.sh
+++ /dev/null
@@ -1,63 +0,0 @@
-#! /bin/sh
-# Copyright (C) 2005-2012 Free Software Foundation, Inc.
-#
-# This program 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.
-#
-# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Make sure 'missing texinfo' does not create empty files.
-# Report from Bob Proulx.
-
-. ./defs || Exit 1
-
-echo info_TEXINFOS = bar.texi >Makefile.am
-echo grepme >bar.info
-$sleep
-cat >bar.texi <<EOF
-@setfilename bar.info
-EOF
-
-echo AC_OUTPUT >>configure.ac
-
-cat >makeinfo <<\EOF
-#!/bin/sh
-# This script
-# 1. fails so 'missing' can take over
-# 2. does not understand '--version' so 'missing' thinks 'makeinfo' isn't
-#    installed
-exec false
-EOF
-
-chmod +x makeinfo
-
-PATH=`pwd`$PATH_SEPARATOR$PATH
-export PATH
-
-# Otherwise configure might pick up a working makeinfo from the
-# environment.  Seen in automake bug#10866.
-unset MAKEINFO || :
-
-$ACLOCAL
-$AUTOCONF
-$AUTOMAKE --add-missing
-
-./configure
-$MAKE
-grep grepme bar.info
-test -f bar.info
-
-# We should not create a missing bar.info.
-rm -f bar.info
-$MAKE && Exit 1
-test ! -f bar.info
-
-: