autoconf/man/common.w

#! /bin/sh
# help-extract wrapper, see build-aux/help-extract.pl and man/local.mk
exec "${PERL-perl}" "${top_srcdir}/build-aux/help-extract.pl" \
   bin/common.in "$@"
Generate manpages directly from source code. We generate manpages for autoconf’s installed programs (autoconf, autoheader, etc.) using help2man, which runs each program in order to learn its --help output. Each manpage therefore has a dependency on the existence of the corresponding program, but this dependency is intentionally left out of the Makefile so that one can build from a tarball release (which will include prebuilt manpages) without having help2man installed. But when building from a git checkout with high levels of parallelism (-j20 or so), the missing dependency can lead to build failures, because help2man will try to run the program before it exists. In an earlier patch I tried to work around this with a recursive make invocation in the ‘.x.1’ rule, to ensure the existence of the program. That only traded one concurrency bug for another, now we could have two jobs trying to build the same program simultaneously and they would clobber each other’s work and the build would still fail. Instead, this patch introduces a utility script ‘help-extract.pl’ that reads --help and --version information directly from the source code for each program. This utility, wrapped appropriately for each program, is what help2man now runs. Usage is a little weird because help2man doesn’t let you specify any arguments to the “executable” that it runs, but it works, and lets us write all of the true dependencies of each manpage into the Makefile without naming any file that would be created during a build from a tarball. help-extract.pl is a Perl script, so it introduces no new build-time requirements. A downside is that we have to make sure each of the script sources in bin/, and also part of lib/Autom4te/ChannelDefs.pm, are parseable by help-extract. The most important constraints are that the text output by --help must be defined in a global variable named ‘help’, and its definition has to be formatted just the way these definitions are currently formatted. Similarly for --version. Furthermore, only some non-literal substitutions are possible in these texts; each has to be explicitly supported in help-extract.pl. The current list of supported substitutions is $0, @PACKAGE_NAME@, @VERSION@, @RELEASE_YEAR@, and Autom4te::ChannelDefs::usage. The generated manpages themselves are character-for-character identical before and after this patch. * build-aux/help-extract.pl: New build script that extracts --help and --version output from manpages. * man/autoconf.w, man/autoheader.w, man/autom4te.w, man/autoreconf.w * man/autoscan.w, man/autoupdate.w, man/ifnames.w: New shell scripts which wrap build-aux/help-extract.pl. * man/local.mk: Generate each manpage by running help2man on the corresponding .w script, not on the built utility itself. Revise all dependencies to match. * bin/autoconf.as: Rename ‘usage’ variable to ‘help’ and ‘help’ variable to ‘usage_err’. * bin/autoheader.in: Call Autom4te::ChannelDefs::usage with no function-call parentheses, matching all the other scripts. * bin/autom4te.in: Initialize $version with a regular double-quoted string, not a heredoc, matching all the other scripts. * bin/autoscan.in: Remove global variable $configure_scan. 2020-08-22 01:13:38 +08:00			`#! /bin/sh`
			`# help-extract wrapper, see build-aux/help-extract.pl and man/local.mk`
			`exec "${PERL-perl}" "${top_srcdir}/build-aux/help-extract.pl" \`
			`bin/common.in "$@"`