[PATCH 6/6] Add --pull, --gen options to build-aux/bootstrap

[Paul Eggert <eggert@cs.ucla.edu>]

This supports a single bootstrap script with --pull and --gen
options, as an alternative to separate autogen.sh and autopull.sh
and bootstrap-funclib.sh auxiliary files.
* top/bootstrap: With --version, also output library version.
Support update of package that has only the bootstrap script,
and not the other three files.
---
 ChangeLog            |  9 +++++++++
 build-aux/bootstrap  | 26 +++++++++++++++++++++++---
 doc/gnulib-tool.texi | 13 ++++++++-----
 doc/gnulib.texi      | 23 ++++++++++++++++++-----
 top/bootstrap        | 26 +++++++++++++++++++++++---
 5 files changed, 81 insertions(+), 16 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 331e31a68b..12c14a2e7a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,18 @@
 2022-12-27  Paul Eggert  <eggert@cs.ucla.edu>
 
+	Add --pull, --gen options to build-aux/bootstrap
+	This supports a single bootstrap script with --pull and --gen
+	options, as an alternative to separate autogen.sh and autopull.sh
+	and bootstrap-funclib.sh auxiliary files.
+	* top/bootstrap: With --version, also output library version.
+	Support update of package that has only the bootstrap script,
+	and not the other three files.
+
 	Support packages with just 'bootstrap'
 	* top/bootstrap: With --version, also output library version.
 	Support update of package that has only the bootstrap script,
 	and not the other three files.
+
 	* top/bootstrap-funclib.sh (scriptlibversion): Rename
 	from scriptversion.  All uses changed.  This way we
 	can distinguish script from script library versions.
diff --git a/build-aux/bootstrap b/build-aux/bootstrap
index d40cd01162..b1a4cc17de 100755
--- a/build-aux/bootstrap
+++ b/build-aux/bootstrap
@@ -3,7 +3,7 @@
 
 # Bootstrap this package from checked-out sources.
 
-scriptversion=2022-12-27.05; # UTC
+scriptversion=2022-12-27.07; # UTC
 
 # Copyright (C) 2003-2022 Free Software Foundation, Inc.
 #
@@ -1335,6 +1335,11 @@ Optional environment variables:
   GNULIB_URL               Cloneable URL of the gnulib repository.
 
 Options:
+
+  --pull                   Do phase 1: pull files from network
+  --gen                    Do phase 2: generate from local files.
+                           (The default is to do both phases.)
+
   --gnulib-srcdir=DIRNAME  specify the local directory where gnulib
                            sources reside.  Use this if you already
                            have gnulib sources on your machine, and
@@ -1346,11 +1351,13 @@ Options:
                            and history on your machine, and do not want
                            to waste your bandwidth downloading them again.
                            Defaults to \$GNULIB_REFDIR
+
   --bootstrap-sync         if this bootstrap script is not identical to
                            the version in the local gnulib sources,
                            update this script, and then restart it with
                            /bin/sh or the shell \$CONFIG_SHELL
   --no-bootstrap-sync      do not check whether bootstrap is out of sync
+
   --copy                   copy files instead of creating symbolic links
   --force                  attempt to bootstrap even if the sources seem
                            not to have been checked out
@@ -1405,6 +1412,10 @@ EOF
 
 # Parse options.
 
+# Whether to pull and generate.
+pull=false
+gen=false
+
 # Whether to use copies instead of symlinks.
 copy=false
 
@@ -1423,6 +1434,10 @@ do
     echo "$copyright"
     exit 0
     ;;
+  --pull)
+    pull=true;;
+  --gen)
+    gen=true;;
   --gnulib-srcdir=*)
     GNULIB_SRCDIR=${option#--gnulib-srcdir=};;
   --gnulib-refdir=*)
@@ -1444,6 +1459,9 @@ do
   esac
 done
 
+# Default is to do both.
+$pull || $gen || pull=true gen=true
+
 $use_git || test -n "$GNULIB_SRCDIR" \
   || die "Error: --no-git requires \$GNULIB_SRCDIR environment variable or --gnulib-srcdir option"
 test -z "$GNULIB_SRCDIR" || test -d "$GNULIB_SRCDIR" \
@@ -1468,7 +1486,7 @@ echo "$0: Bootstrapping from checked-out $package sources..."
 export GNULIB_SRCDIR
 export GNULIB_REFDIR
 
-if $use_git || test -z "$SKIP_PO"; then
+if $pull && { $use_git || test -z "$SKIP_PO"; }; then
   autopull \
       `if $bootstrap_sync; then echo ' --bootstrap-sync'; else echo ' --no-bootstrap-sync'; fi` \
       `if test -z "$checkout_only_file"; then echo ' --force'; fi` \
@@ -1477,10 +1495,12 @@ if $use_git || test -z "$SKIP_PO"; then
     || die "could not fetch auxiliary files"
 fi
 
-autogen \
+if $gen; then
+ autogen \
     `if $copy; then echo ' --copy'; fi` \
     `if test -z "$checkout_only_file"; then echo ' --force'; fi` \
   || die "could not generate auxiliary files"
+fi
 
 # ----------------------------------------------------------------------------
 
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index ba1598fd9a..808e1e8279 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -987,7 +987,8 @@ time, three ways of handling version control have evolved.
 
 In the cases (A) and (B), a ``git submodule'' is used to reference
 the precise commit of the gnulib repository, so that each developer
-running @file{autopull.sh} will get the same version of all gnulib-provided
+running @samp{./bootstrap --pull} or @file{autopull.sh}
+will get the same version of all gnulib-provided
 files.
 
 The alternative is to always follow the newest Gnulib automatically.
@@ -1031,10 +1032,12 @@ $ git syncsub
 @end smallexample
 
 @item (B)
-In this approach, the @code{autopull.sh} program (see @ref{Developer tools})
-is used to aid a developer in using this setup.  You copy this program and
-its companion files into your package and place them under version control.
-It can be customized using @file{bootstrap.conf} which you also put under
+In this approach, the @code{build-aux/bootstrap} or @code{autopull.sh}
+program (see @ref{Developer tools}) is used to aid a developer in
+using this setup.  You copy this program (and if it's
+@code{autopull.sh}, its companion files) into your package and place
+the copy or copies under version control.  The program can be
+customized using @file{bootstrap.conf} which you also put under
 version control.
 
 @item (C)
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index eeb9b81f8a..816bf2a3f2 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -7055,7 +7055,7 @@ otherwise have a hard time building your package.
 @node Utilities for Makefiles
 @section Utilities for Makefiles
 
-These are a couple of programs that are often useful in Makefiles.  Some
+These programs can be used in Makefiles.  Some
 of them are also described in
 @ifinfo
 @ref{Auxiliary Programs,,,automake}.
@@ -7105,7 +7105,7 @@ targets depend upon.
 @node Developer tools
 @section Programs for developing in Git checkouts
 
-These are a couple of programs that help when developing in a Git
+These programs can help when developing in a Git
 checkout.  The maintainer of the package copies these programs into the
 version control of the package, so that co-developers can use these
 tools right away.
@@ -7134,9 +7134,12 @@ omitted from version control.  Usually this means that it invokes
 @code{gnulib-tool} and @code{automake}, that generate files from other
 files.
 
-@code{bootstrap} is a wrapper around both: It invokes @code{autopull.sh}
-and then immediately @code{autogen.sh}.@*
-Note: Because this program mixes version control management and
+@code{bootstrap} is a wrapper around both:
+@code{./bootstrap --pull} is equivalent to @code{./autopull.sh},
+@code{./bootstrap --gen} is equivalent to @code{./autogen.sh}.
+Plain @code{./bootstrap} is equivalent to @code{./autopull.sh}
+immediately followed by @code{./autogen.sh}; however, because plain
+@code{./bootstrap} mixes version control management and
 generation of files in non-obvious ways, it has a number of usability
 issues for the advanced developer.
 
@@ -7146,6 +7149,16 @@ programs.  It is not meant to be used directly.
 All three programs make use of a configuration file, called
 @code{bootstrap.conf}.
 
+@item build-aux/bootstrap
+This acts like @code{top/bootstrap}, except it does not
+need the companion files @code{autogen.sh},
+@code{autopull.sh}, and @code{bootstrap-funclib.sh}
+so it avoids some clutter in your project's top level directory.
+With this approach, you update via @code{./bootstrap --pull} and
+@code{./bootstrap --gen} instead of via @code{./autopull.sh} and
+@code{./autogen.sh}.  Otherwise this approach acts similarly, and
+uses the same @code{bootstrap.conf} file.
+
 @item build-aux/bootstrap.conf
 This is the template configuration file.  After copying it into the
 top-level directory of your package, you need to customize it.
diff --git a/top/bootstrap b/top/bootstrap
index 365c378d42..f6ec8fecee 100755
--- a/top/bootstrap
+++ b/top/bootstrap
@@ -1,7 +1,7 @@
 #! /bin/sh
 # Bootstrap this package from checked-out sources.
 
-scriptversion=2022-12-27.05; # UTC
+scriptversion=2022-12-27.07; # UTC
 
 # Copyright (C) 2003-2022 Free Software Foundation, Inc.
 #
@@ -48,6 +48,11 @@ Optional environment variables:
   GNULIB_URL               Cloneable URL of the gnulib repository.
 
 Options:
+
+  --pull                   Do phase 1: pull files from network
+  --gen                    Do phase 2: generate from local files.
+                           (The default is to do both phases.)
+
   --gnulib-srcdir=DIRNAME  specify the local directory where gnulib
                            sources reside.  Use this if you already
                            have gnulib sources on your machine, and
@@ -59,11 +64,13 @@ Options:
                            and history on your machine, and do not want
                            to waste your bandwidth downloading them again.
                            Defaults to \$GNULIB_REFDIR
+
   --bootstrap-sync         if this bootstrap script is not identical to
                            the version in the local gnulib sources,
                            update this script, and then restart it with
                            /bin/sh or the shell \$CONFIG_SHELL
   --no-bootstrap-sync      do not check whether bootstrap is out of sync
+
   --copy                   copy files instead of creating symbolic links
   --force                  attempt to bootstrap even if the sources seem
                            not to have been checked out
@@ -118,6 +125,10 @@ EOF
 
 # Parse options.
 
+# Whether to pull and generate.
+pull=false
+gen=false
+
 # Whether to use copies instead of symlinks.
 copy=false
 
@@ -136,6 +147,10 @@ do
     echo "$copyright"
     exit 0
     ;;
+  --pull)
+    pull=true;;
+  --gen)
+    gen=true;;
   --gnulib-srcdir=*)
     GNULIB_SRCDIR=${option#--gnulib-srcdir=};;
   --gnulib-refdir=*)
@@ -157,6 +172,9 @@ do
   esac
 done
 
+# Default is to do both.
+$pull || $gen || pull=true gen=true
+
 $use_git || test -n "$GNULIB_SRCDIR" \
   || die "Error: --no-git requires \$GNULIB_SRCDIR environment variable or --gnulib-srcdir option"
 test -z "$GNULIB_SRCDIR" || test -d "$GNULIB_SRCDIR" \
@@ -181,7 +199,7 @@ echo "$0: Bootstrapping from checked-out $package sources..."
 export GNULIB_SRCDIR
 export GNULIB_REFDIR
 
-if $use_git || test -z "$SKIP_PO"; then
+if $pull && { $use_git || test -z "$SKIP_PO"; }; then
   autopull \
       `if $bootstrap_sync; then echo ' --bootstrap-sync'; else echo ' --no-bootstrap-sync'; fi` \
       `if test -z "$checkout_only_file"; then echo ' --force'; fi` \
@@ -190,10 +208,12 @@ if $use_git || test -z "$SKIP_PO"; then
     || die "could not fetch auxiliary files"
 fi
 
-autogen \
+if $gen; then
+ autogen \
     `if $copy; then echo ' --copy'; fi` \
     `if test -z "$checkout_only_file"; then echo ' --force'; fi` \
   || die "could not generate auxiliary files"
+fi
 
 # ----------------------------------------------------------------------------
 
-- 
2.25.1