Various tweaks to bootstrap and upgrade scripts

2 files changed, 25 insertions, 99 deletions

diff --git a/bootstrap b/bootstrap
index ad01f1d..cebdab3 100755
--- a/bootstrap
+++ b/bootstrap
@@ -5,103 +5,25 @@
 #    and only generate PDFs for web publishing? Maybe decide when moving
 #    to ad hoc rules?
 
-# @@ Describe filesystem structure, created configurations, symlinks.
-
-# --ssh --clean --extra --module rust --cxx g++-7 --cfg gcc7
-# --no-clone --no-symlink --no-libs --no-modules --cxx g++-7 --cfg gcc7-tsan --coptions "-Wall -Wextra -Werror -g -fsanitize=thread"
+# Boostrap the build2 development setup.
+#
+# See HOWTO/setup-build2-for-development.md for step by step instructions.
+#
+# Typical command lines for "full" development setup:
+#
+# --ssh --clean --extra --module rust --cxx g++-7 --cfg gcc7 --loptions "-fuse-ld=gold -Wl,--threads,--thread-count,4"
+#
+# Additional configuration:
+#
+# --no-clone --no-symlink --no-libs --no-modules --cxx g++-7 --cfg gcc7-tsan --coptions "-Wall -Wextra -Werror -g -fsanitize=thread" --loptions "-fuse-ld=gold -Wl,--threads,--thread-count,4"
+#
+# To initialize any additional projects:
+#
 # bdep init -d <proj> -A builds/gcc7 @gcc7
-
-# Boostrap the build2 development environment.
 #
 # Note that this script runs git-update-index commands specified in the
-# README-GIT files of cloned repositories.
-#
-# This script assumes the following steps have been performed:
-#
-# 1. The latest staged toolchain has been temporarily installed somewhere
-#    other than /usr/local (e.g., /tmp/build2-install) and is in PATH.
-#    Hint: use --local --no-modules when building the staged toolchain to
-#    speed things up seeing that this is a throw-away installation:
-#
-#    sh build2-install-...-stage.sh --local --no-modules /tmp/build2-install
-#
-# 2. The CLI and ODB compilers have been built and are either installed (if
-#    you don't plan to contribute to them) or symlinked in /usr/local/bin/.
-#    For the latter case they would typically go to ~/work/{cli,odb/}, for
-#    example, for CLI:
-#
-#    NOTE: clone using the git.codesynthesis.com:/var/scm/... SSH URL if you
-#          have rw access.
-#
-#    mkdir -p ~/work/cli
-#    cd ~/work/cli
-#    git clone --recursive https://git.codesynthesis.com/cli/cli.git
-#    cd cli
-#    ... see README.md for instructions
-#    ... use config.cc.coptions="-Wall -Wextra -Werror -g3 -fsanitize=address -fsanitize=undefined -fno-omit-frame-pointer"
-#    b
-#    sudo ln -s "$(pwd)/cli/cli/cli" /usr/local/bin/cli
-#    which cli
-#    cli --version
-#
-#    For ODB (no sanitizer use is currently possible due to the way GCC is
-#    built):
-#
-#    mkdir -p ~/work/odb
-#    cd ~/work/odb
-#    git clone --recursive https://git.codesynthesis.com/odb/odb.git
-#    cd odb
-#    bdep init -C ../builds/gccN-asan @gccN-asan cc \
-#      config.cxx=g++-N                             \
-#      config.cc.coptions="-Wall -Wextra -Werror -g3"
-#    b
-#    sudo ln -s "$(pwd)/odb/odb"    /usr/local/bin/odb
-#    sudo ln -s "$(pwd)/odb/odb.so" /usr/local/bin/odb.so
-#    which odb
-#    odb --version
-#
-# Once this is done, you should be able to:
-#
-# NOTE: clone using the git.build2.org:/var/scm/... SSH URL and pass the
-#       --ssh bootstrap option if you have rw access.
-#
-# mkdir -p ~/work/build2
-# cd ~/work/build2
-# git clone --recursive https://git.build2.org/etc.git
-# PATH="/tmp/build2-install/bin:$PATH" etc/bootstrap
-#
-# After a successful bootstrap you can remove the staged toolchain.
-#
-# Also a few notes and tips on the development process: Because the toolchain
-# is used for its own development you will sometimes find yourself in a
-# situation where one or more tools in the toolchain are no longer runnable or
-# functioning correctly but to fix this you need to be able to run those
-# tools. This can happen, for example, because of the linking errors or
-# because the version (and therefore the name) of one of the shared libraries
-# has changed as a result of updating another part of the toolchain (for
-# instance, updating bpkg can trigger an update of libbpkg and this could make
-# bdep, which also depends on libbpkg, no longer runnable).
-#
-# There are several mechanisms for recovering from such situations. If the
-# build system is functional, it itself and the rest of the toolchain can
-# always be update by first disabling the auto-synchronization hooks (which
-# invoke bdep and bpkg). For example, the following commands should get the
-# toolchain back into the fully-functional state:
-#
-# BDEP_SYNC=0 b build2/build2/ bpkg/bpkg/ bdep/bdep/
-#             b build2/build2/ bpkg/bpkg/ bdep/bdep/
-#
-# If the build system itself is not functional, it can always be rebuilt using
-# the bootstrapped build system (b-boot; built by this script). For example:
-#
-# BDEP_SYNC=0 b-boot build2/build2/
-# BDEP_SYNC=0 b      build2/build2/
-#
-# Note that the bootstrap build system can only be used to update build2. It
-# also makes sense to rebuild it from time to time to keep it reasonably up to
-# date with master. Normally this is done when master is assumed to be in a
-# reasonably good shape. See build2/INSTALL for details on the bootstrap build
-# system.
+# README-GIT files of cloned repositories. It also expected the staged
+# toolchain, CLI, and ODB to be runnable (i.e., already in PATH).
 #
 # Options:
 #
@@ -132,7 +54,8 @@
 # --clean
 #    Clean (or clone if does not exist) the source directories (remove .bdep/,
 #    forwarded configurations) and the configuration directories. This is
-#    primarily useful to re-initialized an already initialized setup.
+#    primarily useful to re-initialized an already initialized (or failed)
+#    setup.
 #
 # --no-libs
 #    Do not create an extra configuration for libraries. Having such a
@@ -150,15 +73,18 @@
 # --coptions
 # --loptions
 #    Compiler and linker options to use. By default a debug build with
-#    ASAN/UBSAN and parallel gold linking is configured:
+#    ASAN/UBSAN is configured:
 #
 #    -Wall -Wextra -Werror -g -fsanitize=address -fsanitize=undefined -fno-omit-frame-pointer
-#    -fuse-ld=gold -Wl,--threads,--thread-count,4
 #
 #    To configure TSAN, use the following coptions instead:
 #
 #    -Wall -Wextra -Werror -g -fsanitize=thread
 #
+#    To enable parallel linking with gold, use the following loptions:
+#
+#    -fuse-ld=gold -Wl,--threads,--thread-count,4
+#
 owd="$(pwd)"
 trap "{ cd '$owd'; exit 1; }" ERR
 set -o errtrace # Trap in functions.
@@ -196,7 +122,7 @@ libs=true
 cxx=g++
 cfg=gcc
 copt="-Wall -Wextra -Werror -g -fsanitize=address -fsanitize=undefined -fno-omit-frame-pointer"
-lopt="-fuse-ld=gold -Wl,--threads,--thread-count,4"
+lopt=
 popt=
 
 while [ $# -gt 0 ]; do
diff --git a/upgrade b/upgrade
index 117f347..ef5fc7e 100755
--- a/upgrade
+++ b/upgrade
@@ -8,7 +8,7 @@
 # In each project of the toolchain.
 #
 # Note that we can't just do that because as soon as we drop some dependency
-# package, the tools (b, bppg, etc) become non-runnable (missing shared
+# package, the tools (b, bpkg, etc) become non-runnable (missing shared
 # libraries, etc).
 #
 # Finally, this script only upgrades the default configurations (including