From 0fb020fa6e1959f06f44427f4b6b0ca99e0a2745 Mon Sep 17 00:00:00 2001 From: Ralf Wildenhues Date: Sun, 21 Dec 2008 22:38:37 +0100 Subject: [PATCH] Revamp semantics for `missing help2man' and manpage distribution. Previously, `missing help2man' would create a missing man page containing an error message, and exit 1. This does not play well with `make': the next run will see this particular man page as being up to date, and will only error out on the next generated man page, if any; repeat until all pages are done. This patch changes `missing' to exit successfully in this case, but `make dist' will ensure that no such man pages are packaged. * lib/missing: Exit successfully even if we create a replacement page due to missing help2man. * automake.in (make_paragraphs): Define %HAVE-MANS% to be true if this makefile deals with man pages. * lib/am/distdir.am (distdir): If %INSTALL-MAN% and %HAVE-MANS%, check that no man page in $(MANS) contains the replacement text from `missing'. * tests/man4.test: New test. * tests/Makefile.am: Update. * NEWS: Reorder a bit, update. * THANKS: Update. Report by Werner Lemberg and Karl Berry. Signed-off-by: Ralf Wildenhues --- ChangeLog | 21 +++++++++++ NEWS | 20 +++++++++- THANKS | 1 + automake.in | 1 + doc/Makefile.in | 13 +++++++ lib/am/distdir.am | 26 +++++++++++++ lib/missing | 4 +- tests/Makefile.am | 1 + tests/Makefile.in | 1 + tests/man4.test | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 193 insertions(+), 4 deletions(-) create mode 100755 tests/man4.test diff --git a/ChangeLog b/ChangeLog index b425a42b7..173afd2ba 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,26 @@ 2008-12-21 Ralf Wildenhues + Revamp semantics for `missing help2man' and manpage distribution. + Previously, `missing help2man' would create a missing man page + containing an error message, and exit 1. This does not play + well with `make': the next run will see this particular man page + as being up to date, and will only error out on the next + generated man page, if any; repeat until all pages are done. + This patch changes `missing' to exit successfully in this case, + but `make dist' will ensure that no such man pages are packaged. + * lib/missing: Exit successfully even if we create a replacement + page due to missing help2man. + * automake.in (make_paragraphs): Define %HAVE-MANS% to be true + if this makefile deals with man pages. + * lib/am/distdir.am (distdir): If %INSTALL-MAN% and %HAVE-MANS%, + check that no man page in $(MANS) contains the replacement text + from `missing'. + * tests/man4.test: New test. + * tests/Makefile.am: Update. + * NEWS: Reorder a bit, update. + * THANKS: Update. + Report by Werner Lemberg and Karl Berry. + Do not use 'global' for makefile-wide settings. * doc/automake.texi (Linking, Libtool Flags) (Program and Library Variables, Flag Variables Ordering): diff --git a/NEWS b/NEWS index e566172cd..6fcc1a535 100644 --- a/NEWS +++ b/NEWS @@ -125,8 +125,6 @@ New in 1.10a: - AM_SUBST_NOTMAKE may prevent substitution of AC_SUBSTed variables, useful especially for multi-line values. - - The `missing' script works better with versioned tool names. - - Automake's early configure-time sanity check now diagnoses an unsafe absolute source directory name and makes configure fail. @@ -154,6 +152,24 @@ Bugs fixed in 1.10a: extra quoting used internally by Autoconf 2.62 and newer (it used to work only without the `--file=' bit). + - The `missing' script works better with versioned tool names. + + - Semantics for `missing help2man' have been revamped: + + Previously, if `help2man' was not present, `missing help2man' would have + the following semantics: if some man page was out of date but present, then + a warning would be printed, but the exit status was 0. If the man page was + not present at all, then `missing' would create a replacement man page + containing an error message, and exit with a status of 2. This does not play + well with `make': the next run will see this particular man page as being up + to date, and will only error out on the next generated man page, if any; + repeat until all pages are done. This was not desirable. + + These are the new semantics: if some man page is not present, and help2man + is not either, then `missing' will warn and generate the replacement page + containing the error message, but exit successfully. However, `make dist' + will ensure that no such bogus man pages are packaged into a tarball. + * Bugs introduced by 1.10: - Fix output of dummy dependency files in presence of post-processed diff --git a/THANKS b/THANKS index 700f13bbb..cb147d9a2 100644 --- a/THANKS +++ b/THANKS @@ -328,6 +328,7 @@ Vincent Lefevre vincent@vinc17.org Volker Boerchers vboerchers@tecon.de Werner John john@oswf.de Werner Koch wk@isil.d.shuttle.de +Werner Lemberg wl@gnu.org William Pursell bill.pursell@gmail.com William S Fulton wsf@fultondesigns.co.uk Yann Droneaud ydroneaud@meuh.eu.org diff --git a/automake.in b/automake.in index 24bb1931d..5523d7509 100755 --- a/automake.in +++ b/automake.in @@ -6641,6 +6641,7 @@ sub make_paragraphs ($%) 'INSTALL-INFO' => ! option 'no-installinfo', 'INSTALL-MAN' => ! option 'no-installman', + 'HAVE-MANS' => !! var ('MANS'), 'CK-NEWS' => !! option 'check-news', 'SUBDIRS' => !! var ('SUBDIRS'), diff --git a/doc/Makefile.in b/doc/Makefile.in index e692797b0..ee9483dbc 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -526,6 +526,19 @@ distclean-tags: -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags distdir: $(DISTFILES) + @list='$(MANS)'; if test -n "$$list"; then \ + list=`for p in $$list; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + if test -f "$$d$$p"; then echo "$$d$$p"; else :; fi; done`; \ + if test -n "$$list" && \ + grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the \`missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically \`make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi; \ + else :; fi @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ list='$(DISTFILES)'; \ diff --git a/lib/am/distdir.am b/lib/am/distdir.am index 218e65aef..81d2210b8 100644 --- a/lib/am/distdir.am +++ b/lib/am/distdir.am @@ -80,6 +80,32 @@ if %?CK-NEWS% endif %?CK-NEWS% endif %?TOPDIR_P% ## +## `missing help2man' may have created some bogus man pages. Ensure they +## are not distributed. +## +if %?INSTALL-MAN% +if %?HAVE-MANS% + @list='$(MANS)'; if test -n "$$list"; then \ + list=`for p in $$list; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ +## Note that we check existing man pages here only. If there are man pages +## which are not distributed, and may be generated only conditionally, then +## we should not error out because of them. This could be refined to take +## into account only dist_*_MANS, but then we'd be missing out on those +## the user distributes with EXTRA_DIST. + if test -f "$$d$$p"; then echo "$$d$$p"; else :; fi; done`; \ + if test -n "$$list" && \ + grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the \`missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically \`make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi; \ + else :; fi +endif %?HAVE-MANS% +endif %?INSTALL-MAN% +## ## Only for the top dir. ## if %?TOPDIR_P% diff --git a/lib/missing b/lib/missing index 32e23d236..f359dae7a 100755 --- a/lib/missing +++ b/lib/missing @@ -1,7 +1,7 @@ #! /bin/sh # Common stub for a few missing GNU programs while installing. -scriptversion=2008-12-13.14 +scriptversion=2008-12-21.33 # Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005, 2006, # 2008 Free Software Foundation, Inc. @@ -285,7 +285,7 @@ WARNING: \`$1' is $msg. You should only need it if else test -z "$file" || exec >$file echo ".ab help2man is required to generate this page" - exit 1 + exit $? fi ;; diff --git a/tests/Makefile.am b/tests/Makefile.am index c2ace7843..1ed0fd304 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -396,6 +396,7 @@ makevars.test \ man.test \ man2.test \ man3.test \ +man4.test \ mclean.test \ mdate.test \ mdate2.test \ diff --git a/tests/Makefile.in b/tests/Makefile.in index f71bb7cab..c88496af9 100644 --- a/tests/Makefile.in +++ b/tests/Makefile.in @@ -550,6 +550,7 @@ makevars.test \ man.test \ man2.test \ man3.test \ +man4.test \ mclean.test \ mdate.test \ mdate2.test \ diff --git a/tests/man4.test b/tests/man4.test new file mode 100755 index 000000000..558c88093 --- /dev/null +++ b/tests/man4.test @@ -0,0 +1,109 @@ +#! /bin/sh +# Copyright (C) 2008 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 3, 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 . + +# 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 + +set -e + +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 + +## It is a bug that we need to list $(srcdir)/bar.1 explicitly here. +MAINTAINERCLEANFILES = $(dist_man_MANS) $(srcdir)/bar.1 +END + +cat >>configure.in <<'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 + +cat > help2man <<'END' +#! /bin/sh +# fake help2man script that lets `missing' think it is not installed +exit 127 +END + +chmod +x foo bar help2man +save_PATH=$PATH +PATH=`pwd`:$PATH + +$ACLOCAL +$AUTOMAKE +$AUTOCONF +./configure +$MAKE +$MAKE dist && Exit 1 +$MAKE distcheck && Exit 1 +$MAKE distclean + +mkdir build +cd build +../configure +$MAKE +$MAKE dist 2>stderr && { cat stderr >&2; Exit 1; } +cat stderr >&2 +grep 'install help2man' stderr +$MAKE distcheck 2>stderr && { cat stderr >&2; Exit 1; } +cat stderr >&2 +grep 'install help2man' stderr + +rm -f ../help2man +PATH=$save_PATH +export PATH + +# If help2man is installed, then ensure that the recommendation works. +if (help2man --version) >/dev/null 2>&1; then + $MAKE maintainer-clean + ../configure + $MAKE + $MAKE distcheck +fi +: -- 2.11.4.GIT