Re: [PATCH] build: do not require help2man at build-from-tarball time

[Stefano Lattarini]

On 09/16/2012 01:46 AM, Mike Frysinger wrote:
>
> i wonder why coreutils ships with help2man at all considering it's released 
> as 
> a dedicated package.  the missing helper script can already handle the case 
> where help2man isn't installed and output a stub man page.
>
Not anymore, starting from (yet-to-be-released) Automake 1.13; see commit
a22717df, whose commit message I copy here for clarity:

    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 files 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 our
    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.