Minor updates to build scripts

8 files changed, 354 insertions, 156 deletions

diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
index f1ffc1b..3dc9cb9 100644
--- a/BOOTSTRAP-MINGW.cli
+++ b/BOOTSTRAP-MINGW.cli
@@ -3,11 +3,24 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing with Windows Bootstrap, to build with MinGW you can either perform
-the following steps manually or, if you are happy with using the defaults, run
-the \c{build-mingw.bat} batch file. It performs (and echoes) the same set of
-steps as outline below but only allows you to customization the compiler and
-installation directory (run \c{build-mingw.bat /?} for usage) and you can also
+Continuing with \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you are
+using your own MinGW distribution, then the resulting \c{build2} binaries will
+most likely required a number of DLLs in order to run. It is therefore
+recommended that you copy the following files from your MinGW \c{bin\\}
+subdirectory to \c{C:\\build2\\bin\\} (\c{*} in the last name will normally be
+\c{dw2-1}, \c{seh-1}, or \c{sjlj-1}):
+
+\
+libwinpthread-1.dll
+libstdc++-6.dll
+libgcc_s_*.dll
+\
+
+To build with MinGW you can either perform the following steps manually or, if
+after reviewing the steps, you are happy with using the defaults, run the
+\c{build-mingw.bat} batch file. It performs (and echoes) the same set of steps
+as outline below but only allows you to customization the compiler and
+installation directory (run \c{build-mingw.bat /?} for usage). You can also
 specify an alternative package repository with the \c{BUILD2_REPO} environment
 variable.
 
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
index ea10c74..835cf50 100644
--- a/BOOTSTRAP-MSVC.cli
+++ b/BOOTSTRAP-MSVC.cli
@@ -3,24 +3,24 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-Continuing with Windows Bootstrap, if you have already started an appropriate
-Visual Studio command prompt, then you can continue using it. Otherwise, start
-the \"x64 Native Tools Command Prompt\" if you are on 64-bit Windows or \"x86
-Native Tools Command Prompt\" if you are on 32-bit. Also set the \c{PATH}
-environment variable:
+Continuing with \l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}, if you have
+already started an appropriate Visual Studio command prompt, then you can
+continue using it. Otherwise, start the \"x64 Native Tools Command Prompt\" if
+you are on 64-bit Windows or \"x86 Native Tools Command Prompt\" if you are on
+32-bit. Also set the \c{PATH} environment variable:
 
 \
 > set PATH=C:\build2\bin;%PATH%
 \
 
 To build with MSVC you can either perform the following steps manually or, if
-you are happy with using the defaults, run the \c{build-msvc.bat} batch file.
-It performs (and echoes) the same set of steps as outline below but only
-allows you to customization the installation directory (run \c{build-msvc.bat
-/?} for usage) and you can also specify an alternative package repository with
-the \c{BUILD2_REPO} environment variable.
+if after reviewing the steps you are happy with using the defaults, run the
+\c{build-msvc.bat} batch file. It performs (and echoes) the same set of steps
+as outline below but only allows you to customization the installation
+directory (run \c{build-msvc.bat /?} for usage). You can also specify an
+alternative package repository with the \c{BUILD2_REPO} environment variable.
 
-For example, you could run thsi batch file (from the above-mentioned command
+For example, you could run this batch file (from the above-mentioned command
 prompt) like this:
 
 \
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index 7b1a125..f97e6f5 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -7,7 +7,7 @@ The following instructions are for bootstrapping \c{build2} on UNIX-like
 operating systems (GNU/Linux, FreeBSD, etc). For Mac OS X first see
 \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}. These instructions should
 also be used for UNIX emulation layers on Windows (for example, MSYS2 or
-Cygwin) where you already have a UNIX shell with standard utilitis.
+Cygwin) where you already have a UNIX shell with standard utilities.
 
 \dl|
 
@@ -58,12 +58,13 @@ Unpack the archive and change to its directory:
 
 ||
 
-Next you can either perform the rest of the steps manually or, if you are
-happy with using the defaults, run the \c{build.sh} shell script. It performs
-(and echoes) the same set of steps as outline below but only allows you to
-customization the compiler and installation directory (run \c{build.sh -h} for
-usage) and you can also specify an alternative package repository with the
-\c{BUILD2_REPO} environment variable.
+Next you can either perform the rest of the steps manually or, if after
+reviewing the steps, you are happy with using the defaults, run the
+\c{build.sh} shell script. It performs (and echoes) the same set of steps as
+outline below but only allows you to customization the compiler, installation
+directory, and a few other things (run \c{build.sh -h} for usage). You can
+also specify an alternative package repository with the \c{BUILD2_REPO}
+environment variable.
 
 For example, this command will use \c{g++-5} and install the toolchain into
 \c{/usr/local/}.
@@ -77,4 +78,176 @@ While this will use Clang and install into \c{/opt/build2}:
 \
 $ ./build.sh --install-dir /opt/build2 --sudo sudo clang++
 \
+
+Note also that about half way (\c{bpkg fetch} on step 6 below) the script will
+stop and prompt you to verify the authenticity of the repository certificate.
+To run the script unattended you can specify the certificate fingerprint with
+the \c{--trust} option.
+
+The end result of the bootstrap process (performed either with the script or
+manually) is the installed toolchain as well as the \c{bpkg} configuration in
+\c{build2-toolchain-X.Y} that can be used to \l{#UPGRADE upgrade} to newer
+versions. It can also be used to uninstall the toolchain:
+
+\
+$ cd build2-toolchain-X.Y
+$ bpkg uninstall build2 bpkg
+\
+
+The rest of this section outlines the manual bootstrap with the step numbering
+continued from the above list.
+
+\dl|
+
+\li|3. Bootstrap, Phase 1\n
+
+First, we build a minimal build system with the provided \c{bootstrap.sh}
+script. Normally the only argument you will pass to this script is the
+C++ compiler to use but there is also a way to specify compile options
+and a few other things; run \c{bootstrap.sh -h} and see the \c{build2/INSTALL}
+file for details.
+
+\
+$ cd build2
+$ ./bootstrap.sh g++
+
+$ build2/b-boot --version
+\
+
+|
+
+\li|\n4. Bootstrap, Phase 2\n
+
+Then, we rebuild the build system with the result of Phase 1 linking
+libraries statically.
+
+\
+$ build2/b-boot config.cxx=g++ config.bin.lib=static
+$ mv build2/b build2/b-boot
+
+$ build2/b-boot --version
+\
+
+|
+
+\li|\n5. Stage\n
+
+On this step the entire toolchain is built and staged. Here you may want
+to adjust a few things, such as the installation directory or the \c{sudo}
+program (remove the \c{config.install.sudo} line if you don't need one).
+
+The strange-looking \c{config.install.data_root=root/stage} means install
+data files (as opposed to executable files) into the \c{stage/} subdirectory
+of wherever \c{config.install.root} points (so in our case it will be
+/usr/local/stage). Note that this subdirectory is temporary and will be
+removed in a few steps. But if you don't like the default location, feel
+free to change it (for example, to \c{/tmp/stage}).
+
+You may also need to remove the \c{config.bin.rpath} line if your target
+doesn't support \i{rpath}. Specifically, if building on Windows (with MSYS or
+Cygwin), remove both \c{.rpath} and \c{.sudo}. But if unsure, leave \c{.rpath}
+in \- if your target doesn't support it, you will get an error and will just
+need to reconfigure without it.
+
+\
+$ run cd ..  # Back to build2-toolchain-X.Y.Z/
+
+$ build2/build2/b-boot configure      \
+  config.cxx=g++                      \
+  config.bin.lib=shared               \
+  config.bin.suffix=-stage            \
+  config.bin.rpath=/usr/local/lib     \
+  config.install.root=/usr/local      \
+  config.install.data_root=root/stage \
+  config.install.sudo=sudo
+
+$ build2/build2/b-boot install
+\
+
+Depending on the installation directory, the installed \c{build2} binaries
+may not be automatically found. On most platforms \c{/usr/local/bin/} is in
+the \c{PATH} environment variable by default and you should be able to run:
+
+\
+$ which b-stage
+/usr/local/bin/b-stage
+
+$ which bpkg-stage
+/usr/local/bin/bpkg-stage
+
+$ b-stage --version
+$ bpkg-stage --version
+\
+
+If, however, you installed, say, into \c{/opt/build2}, then you will need to
+add its \c{bin/} subdirectory to \c{PATH} (re-run the above commands to
+verify):
+
+\
+$ export PATH=\"/opt/build2/bin:$PATH\"
+\
+
+Strictly speaking this is not absolutely necessary and you can adjust
+the rest of the commands to use absolute paths. This, however, does not make
+for very readable examples so below we assume the installation's \c{bin/}
+subdirectory is in \c{PATH}.
+|
+
+\li|\n6. Install\n
+
+Next, we use the staged toolchain to build and install the \"final\" toolchain
+from the package repository using the \c{bpkg} package manager. First, we
+create the \c{bpkg} configuration. The configuration values are pretty similar
+to the previous step and you may want/need to make similar adjustments.
+
+\
+$ cd ..  # Back to build2-build/
+$ mkdir build2-toolchain-X.Y
+$ cd build2-toolchain-X.Y
+
+$ bpkg-stage create \
+  cc \
+  config.cxx=g++ \
+  config.cc.coptions=-O3 \
+  config.bin.lib=shared \
+  config.bin.rpath=/usr/local/lib \
+  config.install.root=/usr/local \
+  config.install.sudo=sudo
+\
+
+Next, we add the package repository, build, and install:
+
+\
+$ bpkg-stage add https://pkg.cppget.org/1/alpha
+$ bpkg-stage fetch
+$ bpkg-stage build build2 bpkg
+$ bpkg-stage install build2 bpkg
+\
+
+Finally, we verify the result:
+
+\
+$ which b
+/usr/local/bin/b
+
+$ which bpkg
+/usr/local/bin/bpkg
+
+$ b-stage --version
+$ bpkg-stage --version
+\
+
+|
+
+\li|\n7. Clean\n
+
+The last thing we need to do is uninstall the staged toolchain:
+
+\
+$ cd ../build2-toolchain-X.Y.Z/  # Back to the bootstrap directory.
+$ b uninstall
+\
+
+||
+
 "
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
index 8fbb26d..245f5c4 100644
--- a/BOOTSTRAP-WINDOWS.cli
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -6,7 +6,7 @@
 The following instructions are for bootstrapping \c{build2} with either MSVC
 or MinGW using the Windows command prompt. If you are using any kind of UNIX
 emulation layer (for example, MSYS2 or Cygwin) and already have a UNIX shell
-with standard utilitis, then you most likely should follow \l{#BOOTSTRAP-UNIX
+with standard utilities, then you most likely should follow \l{#BOOTSTRAP-UNIX
 Bootstrapping on UNIX} instead.
 
 The \c{build2} toolchain on Windows requires a set of extra utilities
diff --git a/build-mingw.bat b/build-mingw.bat
index ed4fc31..2ea001d 100644
--- a/build-mingw.bat
+++ b/build-mingw.bat
@@ -19,7 +19,7 @@ echo Example usage:
 echo.
 echo %0 C:\mingw\bin\g++ D:\build2
 echo.
-echo See the INSTALL file for details.
+echo See the BOOTSTRAP-MINGW file for details.
 echo.
 goto end
 
@@ -120,6 +120,12 @@ build2\build2\b-boot configure^
 build2\build2\b-boot install
 @if errorlevel 1 goto error
 
+where b-stage
+@if errorlevel 1 goto error
+
+where bpkg-stage
+@if errorlevel 1 goto error
+
 b-stage --version
 @if errorlevel 1 goto error
 
@@ -155,6 +161,12 @@ bpkg-stage build --yes build2 bpkg
 bpkg-stage install build2 bpkg
 @if errorlevel 1 goto error
 
+where b
+@if errorlevel 1 goto error
+
+where bpkg
+@if errorlevel 1 goto error
+
 b --version
 @if errorlevel 1 goto error
 
diff --git a/build-msvc.bat b/build-msvc.bat
index 95e194f..96bb79f 100644
--- a/build-msvc.bat
+++ b/build-msvc.bat
@@ -19,7 +19,7 @@ echo Example usage:
 echo.
 echo %0 D:\build2
 echo.
-echo See the INSTALL file for details.
+echo See the BOOTSTRAP-MSVC file for details.
 echo.
 goto end
 
@@ -112,6 +112,12 @@ build2\build2\b-boot configure^
 build2\build2\b-boot install
 @if errorlevel 1 goto error
 
+where b-stage
+@if errorlevel 1 goto error
+
+where bpkg-stage
+@if errorlevel 1 goto error
+
 b-stage --version
 @if errorlevel 1 goto error
 
@@ -147,6 +153,12 @@ bpkg-stage build --yes build2 bpkg
 bpkg-stage install build2 bpkg
 @if errorlevel 1 goto error
 
+where b
+@if errorlevel 1 goto error
+
+where bpkg
+@if errorlevel 1 goto error
+
 b --version
 @if errorlevel 1 goto error
 
diff --git a/build.sh b/build.sh
index 5c2f886..c7610e9 100755
--- a/build.sh
+++ b/build.sh
@@ -4,11 +4,6 @@
 # copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
 # license   : MIT; see accompanying LICENSE file
 
-# @@ Should we add sys:sqlite by default? Or add option?
-# @@ Need to note that script will ask for repository verification.
-# @@ Perhaps a fingerprint to pass to fetch? Once repo is signed?
-# @@ Option for alternative bpkg config dir?
-
 usage="Usage: $0 [-h|--help] [<options>] <cxx>"
 
 # Package repository URL (or path).
@@ -65,7 +60,7 @@ while test $# -ne 0; do
       diag
       diag "$0 --install-dir /opt/build2 --sudo sudo g++"
       diag
-      diag "See the INSTALL file for details."
+      diag "See the BOOTSTRAP-UNIX file for details."
       diag
       exit 0
       ;;
@@ -151,18 +146,6 @@ export PATH
 
 sys="$(build2/config.guess | sed -n 's/^[^-]*-[^-]*-\(.*\)$/\1/p')"
 
-# Bootstrap, stage 1.
-#
-run cd build2
-run ./bootstrap.sh "$cxx"
-run build2/b-boot --version
-
-# Bootstrap, stage 2.
-#
-run build2/b-boot config.cxx="$cxx" config.bin.lib=static
-mv build2/b build2/b-boot
-run build2/b-boot --version
-
 case "$sys" in
   mingw32 | mingw64 | msys | msys2 | cygwin)
     conf_rpath="[null]"
@@ -179,6 +162,18 @@ case "$sys" in
     ;;
 esac
 
+# Bootstrap, stage 1.
+#
+run cd build2
+run ./bootstrap.sh "$cxx"
+run build2/b-boot --version
+
+# Bootstrap, stage 2.
+#
+run build2/b-boot config.cxx="$cxx" config.bin.lib=static
+mv build2/b build2/b-boot
+run build2/b-boot --version
+
 # Stage.
 #
 run cd ..
@@ -194,6 +189,9 @@ config.install.sudo="$conf_sudo"
 
 run build2/build2/b-boot install
 
+run which b-stage
+run which bpkg-stage
+
 run b-stage --version
 run bpkg-stage --version
 
@@ -221,6 +219,9 @@ fi
 run bpkg-stage build --yes build2 bpkg
 run bpkg-stage install build2 bpkg
 
+run which b-stage
+run which bpkg-stage
+
 run b --version
 run bpkg --version
 
diff --git a/doc/intro.cli b/doc/intro.cli
index b0e2cdd..9cc777a 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -93,12 +93,12 @@ build system. The most notable ones are:
 \h#intro|Introduction|
 
 The \c{build2} toolchain is a set of tools designed for building and packaging
-C++ code (though, if it can handle C++, it can handle anything, right?). The
-toolchain currently includes the \i{build system} (\c{build2}), the \i{package
-manager} (\c{bpkg}), and the \i{repository web interface} (\c{brep}). More
-tools, such as the \i{build robot} (\c{bbot}), are in the works. Then there is
-\l{https://cppget.org/ cppget.org} which we hope will become \i{the C++
-package repository}.
+C and C++ code (though, if it can handle C++, it can handle anything,
+right?). The toolchain currently includes the \i{build system} (\c{build2}),
+the \i{package manager} (\c{bpkg}), and the \i{repository web interface}
+(\c{brep}). More tools, such as the \i{build robot} (\c{bbot}), are in the
+works. Then there is \l{https://cppget.org/ cppget.org} (running \c{brep})
+which we hope will become \i{the C++ package repository}.
 
 The goal of this document is to give you a basic idea of what the \c{build2}
 toolchain can do so that you can decide if you are interested and want to learn
@@ -106,12 +106,12 @@ more. Further documentation is referenced at the end of this introduction.
 
 The \c{build2} toolchain is self-hosted and self-packaged (and, yes, it is on
 \l{https://cppget.org/ cppget.org}). It could have then served as its own
-example.  However, before the toolchain can unpack and build itself, we have
-to bootstrap it (that chicken and egg problem again) and this step wouldn't
-serve our goal of quickly learning what \c{build2} is about. So, instead, we
-will start with a customary \i{\"Hello, World!\"} example which you won't yet
-be able to try yourself (but don't worry, complete terminal output will be
-shown). If at the end you find \c{build2} appealing, you can jump right to the
+example.  However, before the toolchain can build itself, we have to bootstrap
+it (that chicken and egg problem again). And this step wouldn't serve our goal
+of quickly learning what \c{build2} is about. So, instead, we will start with
+a customary \i{\"Hello, World!\"} example which you won't yet be able to try
+yourself (but don't worry, complete terminal output will be shown). If at the
+end you find \c{build2} appealing, you can jump right to the
 \l{build2-toolchain-install.xhtml The \c{build2} Toolchain Installation and
 Upgrade} (and, yes, there you get to run that coveted \c{bpkg build bpkg}).
 Once the \c{build2} installation is complete, you can come back to the
@@ -127,9 +127,9 @@ And so, without further ado, let's begin.
 The first step in using \c{bpkg} is to create a \i{configuration}. A
 configuration is a directory where packages that require similar compile
 settings will be built. You can create as many configurations as you want: for
-different C++ compilers, debug/release, 32/64-bit, or even for different days
-of the week, if you are so inclined. Say we are in the mood for a GCC 5
-release build today:
+different C++ compilers, targets (\c{build2} is big on cross-compiling),
+debug/release, 32/64-bit, or even for different days of the week, if you are
+so inclined. Say we are in the mood for a GCC 5 release build today:
 
 \
 $ mkdir hello-gcc5-release
@@ -155,18 +155,19 @@ operation system, everything will work if you use \c{hello-vc14-release} (or
 \c{hello-mingw-release}) on Windows. Just use appropriate paths, compilers,
 and options.
 
-Let's discuss that last command line: \l{bpkg-cfg-create(1) \c{bpkg create}} is
-the command for creating a new configuration. As a side note, if you ever want
-to get help for any \c{bpkg} command, run \c{bpkg help <command>}. To see the
-list of commands, run just \l{bpkg-help(1) \c{bpkg help}} (or see
+Let's discuss that last command line: \l{bpkg-cfg-create(1) \c{bpkg create}}
+is the command for creating a new configuration. As a side note, if you ever
+want to get help for any \c{bpkg} command, run \c{bpkg help \i{<command>}}. To
+see the list of commands, run just \l{bpkg-help(1) \c{bpkg help}} (or see
 \l{bpkg(1)}). While we are at it, if you ever want to see what \c{bpkg} is
-running underneath, there is the \c{-v} option. And if you really want to get
-under the hood, use \l{bpkg-common-options(1) \c{--verbose <level>}}.
+running underneath, there is the \c{-v} (essential commands) and \c{-V} (all
+commands) options. And if you really want to get under the hood, use
+\l{bpkg-common-options(1) \c{--verbose <level>}}.
 
 After the command we have \c{cxx} which is the name of the \c{build2} build
 system module. As you might have guessed, \c{cxx} provides support for the C++
-compilation. By specifying this module during the configuration creation we
-configure it (yes, with those \c{config.cxx...} variables that follow) for the
+compilation. By specifying this module when creating the configuration we
+configure it (yes, with those \c{config.cxx.*} variables that follow) for the
 entire configuration. That is, every package that we will build in this
 configuration and that uses the \c{cxx} module will by default inherit these
 settings.
@@ -184,7 +185,7 @@ $ bpkg create c cxx ...
 \
 
 The problem, of course, is that you may not know what mix of languages those
-projects (or their dependencies) might use. For example the use of C might be
+projects (or their dependencies) might use. For example, the use of C might be
 an implementation detail of a C++ library. To solve this, \c{build2} provides
 another module called \c{cc} which stands for \i{C-common}. So, in this
 context, instead of using the \c{c} and \c{cxx} modules directly, it's a good
@@ -215,7 +216,7 @@ $ bpkg rep-info https://build2.org/pkg/1/hello/stable
 warning: authenticity of the certificate for repository build2.org/hello/stable cannot be established
 certificate is for build2.org, \"Code Synthesis\" <admin@build2.org>
 certificate SHA256 fingerprint:
-FF:DF:7D:38:67:4E:C3:82:65:7E:[...]:29:9A:30:56:B9:77:B9:F2:01:94
+FF:DF:7D:38:67:4E:C3:82:[...]:30:56:B9:77:B9:F2:01:94
 trust this certificate? [y/N]
 \
 
@@ -226,17 +227,17 @@ authenticate a certificate is to compare the displayed fingerprint to the one
 you have received earlier, for example, in an email announcement. The
 repository's about page also lists the fingerprint (see the
 \l{https://build2.org/pkg/hello/?about about page} for our repository). For
-more details on repository signing see \l{bpkg-repository-signing(1)} help
+more details on repository signing see the \l{bpkg-repository-signing(1)} help
 topic.
 
 If we answer \i{yes}, we will see the basic repository information (its
-canonical name, location, certificate subject and fingerprint) followed
+\i{canonical name}, location, certificate subject and fingerprint) followed
 by the list of available packages:
 
 \
 build2.org/hello/stable https://build2.org/pkg/1/hello/stable
 CN=build2.org/O=Code Synthesis/admin@build2.org
-FF:DF:7D:38:67:4E:C3:82:65:7E:[...]:29:9A:30:56:B9:77:B9:F2:01:94
+FF:DF:7D:38:67:4E:C3:82:[...]:30:56:B9:77:B9:F2:01:94
 
 hello/1.0.0
 libhello/1.0.0
@@ -267,7 +268,7 @@ Note that you would normally re-run the \l{bpkg-rep-fetch(1) \c{bpkg fetch}}
 command after you've added another repository or to refresh the list of
 available packages.
 
-Now that \c{bpkg} knows where to get packages, we can finally get down to
+Now that \c{bpkg} knows where to get the packages, we can finally get down to
 business:
 
 \
@@ -282,7 +283,10 @@ build the \c{hello} program which happens to depend on the \c{libhello}
 library. So \c{bpkg} presents us with a \i{plan of action}, that is, the steps
 it will have to perform in order to build us \c{hello} and then asks us to
 confirm that's what we want to do (you can add \c{--yes|-y} to skip the
-confirmation). Let's answer \i{yes} and see what happens:
+confirmation). In the real-world usage the plan will be more complex, with
+upgrades/downgrades, reconfigurations, etc.
+
+Let's answer \i{yes} and see what happens:
 
 \
 libhello-1.0.0.tar.gz        100% of 2428  B 1364 kBps 00m01s
@@ -302,7 +306,7 @@ updated hello/1.0.0
 
 While the output is mostly self-explanatory, in short, \c{bpkg} downloaded,
 unpacked, and configured both packages and then proceeded to building the
-\c{hello} executable which happens to require building of the \c{libhello}
+\c{hello} executable which happens to require building the \c{libhello}
 library. Note that the download progress may look differently on your machine
 depending on which \i{fetch tool} (\c{wget}, \c{curl}, or \c{fetch}) is
 used. If you ever considered giving that \c{-v} option a try, now would be a
@@ -415,9 +419,8 @@ fetching build2.org/hello/testing
 \
 
 Notice that this time we don't see any authentication-related messages or
-prompts since \c{bpkg} remembered (in this configuration) that we trust
-this certificate (the \c{testing} repository naturally uses the same one
-as \c{stable}).
+prompts since \c{bpkg} remembered (in this configuration) that we trust the
+certificate (\c{testing} naturally uses the same one as \c{stable}).
 
 Let's see what's new:
 
@@ -435,10 +438,10 @@ info: dir{hello-1.0.0/} is up to date
 updated hello/1.0.0
 \
 
-Nothing happens. That's because \c{bpkg} will only upgrade (or downgrade) to a
-new version if we explicitly ask it to. As it is now, all dependencies for
-\c{hello} are satisfied and \c{bpkg} is happy to twiddle its thumbs. Let's tell
-\c{bpkg} to build us \c{libhello} instead:
+Why nothing happenned..? That's because \c{bpkg} will only upgrade (or
+downgrade) to a new version if we explicitly ask it to. As things stand, all
+dependencies for \c{hello} are satisfied and \c{bpkg} is happy to twiddle its
+thumbs. Let's tell \c{bpkg} to build us \c{libhello} instead:
 
 \
 $ bpkg build libhello
@@ -467,13 +470,13 @@ update dependent packages? [Y/n]
 Another question. This one has to do with that \c{reconfigure hello} line we
 just talked about. If you were wondering why we were only offered to
 reconfigure and not actually update the dependent package, you should know
-that \c{bpkg} is a very lazy package manager, it only does what it must do.
-It must reconfigure but it doesn't really have to update. And this could be a
-good thing if, for example, you have a hundred dependents in your configuration
-but right now you only want to build just those specific packages. However,
-quite often, you do want to keep all the packages in your configuration up
-to date and \c{bpkg} graciously offers to take care of this task. Ok, let's
-answer \i{yes} again:
+that \c{bpkg} is a very lazy package manager, it only does what it must do,
+not what might be nice to do. It must reconfigure but it doesn't really have
+to update. And this could be a good thing if, for example, you have a hundred
+dependents in your configuration but right now you only want to build just
+those specific packages. However, quite often, you do want to keep all the
+packages in your configuration up to date and \c{bpkg} graciously offers to
+take care of this task. Ok, let's answer \i{yes} again:
 
 \
 ...
@@ -513,10 +516,11 @@ updated libhello/1.1.0
 updated hello/1.0.0
 \
 
-If you were to answer \i{no} to the \"update dependent packages?\" question
-above, it is easy to make sure a package is up-to-date at a later time with
-the \l{bpkg-pkg-update(1) \c{bpkg update}} command (there is also
-\l{bpkg-pkg-clean(1) \c{bpkg clean}}), for example:
+A lot of output but nothing really new. If you were to answer \i{no} to the
+\"update dependent packages?\" question above, it is easy to make sure a
+package is up-to-date at a later time with the \l{bpkg-pkg-update(1) \c{bpkg
+update}} command (there is also \l{bpkg-pkg-clean(1) \c{bpkg clean}}), for
+example:
 
 \
 $ bpkg clean hello
@@ -533,7 +537,7 @@ updated hello/1.0.0
 Let's say we really don't like the direction \c{libhello} is going and would
 rather stick to version \c{1.0.0}. Just like upgrades, downgrades are explicit
 plus, in this case, we need to specify the version (you can also specify
-desired version for upgrades).
+the desired version for upgrades).
 
 \
 $ bpkg build libhello/1.0.0
@@ -580,7 +584,7 @@ $ bpkg build -D -L libhello/1.0.0
 \
 
 Ok, so all this might look nice and all, but we haven't actually seen anything
-of what we've presumably built (it can all be a charade, for all we know). Can
+of what we've presumably built; it can all be a charade, for all we know. Can
 we see some libraries and run the \c{hello} program?
 
 There are several ways we can do this. If the package provides tests (as all
@@ -637,8 +641,8 @@ Hello, World!
 
 The important point here is this: the \c{bpkg} configuration is not some black
 box that you should never look inside. On the contrary, it is a normal and
-predictable concept of the build system and if you understand what you are
-doing, feel free to muck around.
+predictable concept of the build system and as long as you understand what you
+are doing, feel free to muck around.
 
 Another way to get hold of a package's goodies is to install it with
 \l{bpkg-pkg-install(1) \c{bpkg install}}. Let's try that:
@@ -662,9 +666,18 @@ install /opt/hello/share/
 install /opt/hello/share/doc/
 install /opt/hello/share/doc/hello/
 install hello-1.0.0/doc{version}
-
 installed hello/1.0.0
+\
+
+The \c{config.install.sudo} value is the optional \i{sudo}-like program
+that should be used to run the \c{install} program. For those feeling queasy
+running \c{sudo make install}, here is your answer. If you are wondering
+whether you could have specified those \c{config.install.*} values during the
+configuration creation, the answer is yes, indeed!
+
+Let's see what we've got:
 
+\
 $ tree -F /opt/hello/
 /opt/hello/
 ├── bin/
@@ -682,12 +695,7 @@ $ tree -F /opt/hello/
             └── version
 \
 
-The \c{config.install.sudo} value is the optional \i{sudo}-like program
-that should be used to run the \c{install} program. For those feeling queasy
-running \c{sudo make install}, here is your answer. If you are wondering
-whether you could have specified those \c{config.install.*} values during the
-configuration creation, the answer is yes, indeed! Let's try to run the
-installed program:
+We can also try to run the installed program:
 
 \
 $ /opt/hello/bin/hello World
@@ -699,9 +707,9 @@ since \c{hello-1.0.dll} will be installed into \c{bin\\}, next to the
 executable; for once things are working better on Windows.
 
 The problem is with our installation location: the runtime linker won't look
-for \c{libhello-1.0.so} in \c{/opt/hello/lib} unless we somehow tell it to, for
-example, using \c{LD_LIBRARY_PATH} or equivalent.  There are several way we
-can resolve this. We could give up on shared libraries and link our
+for \c{libhello-1.0.so} in \c{/opt/hello/lib} unless we somehow tell it to
+(for example, using \c{LD_LIBRARY_PATH} or equivalent).  There are several way
+we can resolve this. We could give up on shared libraries and link our
 prerequisite libraries statically (\c{config.bin.exe.lib=static}). Or we could
 use the \i{rpath} mechanism:
 
@@ -726,7 +734,6 @@ install /opt/hello/share/
 install /opt/hello/share/doc/
 install /opt/hello/share/doc/hello/
 install hello-1.0.0/doc{version}
-
 installed hello/1.0.0
 
 $ /opt/hello/bin/hello World
@@ -758,22 +765,21 @@ uninstall libhello-1.0.0/hello/hxx{hello}
 uninstall /opt/hello/include/hello/
 uninstall /opt/hello/include/
 uninstall /opt/hello/
-
 uninstalled hello/1.0.0
 
 $ ls /opt/hello
 ls: cannot access /opt/hello: No such file or directory
 \
 
-What if we wanted to use \c{libhello} in our own project? While the installed
-version is always an option, it may not be convenient when we develop our code.
-We may have multiple builds per project, for example, with GCC and Clang to
-catch all the warnings. We may also want to make sure our application works
-well with various versions of \c{libhello} (and maybe even with that heinous
+What if we wanted to use \c{libhello} in our own project? While installing it
+is always an option, this may not be convenient when we develop our code. We
+may have multiple builds per project, for example, with GCC and Clang to catch
+all the warnings. We may also want to make sure our application works well
+with several versions of \c{libhello} (and maybe even with that heinous
 \c{1.1.X}). While we can install different configurations into different
 directories, it's hard to deny things are getting a bit hairy: multiple
-configurations, multiple installations... I guess we will have to get our hands
-into that cookie jar, I mean, configuration, again.
+configurations, multiple installations... I guess we will have to get our
+hands into that cookie jar, I mean, configuration, again.
 
 In fact, let's just start writing our own version of the \c{hello} program
 and see how it goes:
@@ -793,8 +799,8 @@ int main ()
 
 \
 
-What build system will we use? I can't believe you are even asking this
-question!
+What build system shall we use? I can't believe you are even asking this
+question...
 
 \
 $ mkdir build
@@ -819,7 +825,7 @@ exe{hello}: cxx{hello} $libs
 While some of this might not be crystal clear (like why do we have
 \c{bootstrap.build} \i{and} \c{root.build}), I am sure you at least have a
 fuzzy idea of what's going on. And that's enough for what we are after here.
-Completely explaining what's going on here and, more importantly, why it's
+Completely explaining what's going on here and, more importantly, \i{why} it's
 going this way is for another time and place (the \c{build2} build system
 manual).
 
@@ -847,14 +853,16 @@ info: while applying rule cxx.link to update exe{hello}
 info: while applying rule alias to update dir{./}
 \
 
-No magic but we got a hint: looks like we need to tell \c{build2} where
-\c{libhello} is using \c{config.import.libhello}. Without fretting too much
-about what exactly \c{out_root} means, let's point \c{build2} to our \c{bpkg}
-configuration and see what happens. After all, that's where, more or less,
-our \i{out} for \c{libhello} is.
+No magic, unfortunately (or fortunately). But we got a hint: looks like we
+need to tell \c{build2} where \c{libhello} is using
+\c{config.import.libhello}. Without fretting too much about what exactly
+\c{out_root} means, let's point \c{build2} to our \c{bpkg} configuration and
+see what happens. After all, that's where, more or less, our \i{out}-put for
+\c{libhello} is.
 
 \
-$ b config.cxx=g++-5 config.import.libhello=/tmp/hello-gcc5-release
+$ b config.cxx=g++-5 \
+    config.import.libhello=/tmp/hello-gcc5-release
 c++ cxx{hello}
 ld exe{hello}
 \
@@ -909,9 +917,7 @@ $ b config.cxx=g++-5                             \
   config.import.libhello=/tmp/hello-gcc5-release \
   'configure(hello2/@hello2-gcc5-release/)'
 
-mkdir hello2-gcc5-release/build/
-mkdir hello2-gcc5-release/build/bootstrap/
-save hello2-gcc5-release/build/bootstrap/src-root.build
+mkdir -p hello2-gcc5-release/build/
 save hello2-gcc5-release/build/config.build
 \
 
@@ -955,10 +961,7 @@ hello2/
 hello2-gcc5-release/
 
 $ b 'configure(hello2/@/tmp/hello-gcc5-release/hello2/)'
-mkdir -p /tmp/hello-gcc5-release/hello2/
-mkdir /tmp/hello-gcc5-release/hello2/build/
-mkdir /tmp/hello-gcc5-release/hello2/build/bootstrap/
-save /tmp/hello-gcc5-release/hello2/build/bootstrap/src-root.build
+mkdir -p /tmp/hello-gcc5-release/hello2/build/
 save /tmp/hello-gcc5-release/hello2/build/config.build
 
 $ b /tmp/hello-gcc5-release/hello2/
@@ -971,7 +974,7 @@ need to specify any of the \c{config.c*} values this time? Because they are
 inherited from those specified for \c{/tmp/hello-gcc5-release} when we created
 the configuration with \c{bpkg create}. What about \c{config.import.libhello},
 don't we need at least that? Not really \- \c{libhello} will be found
-automatically since it is part of the same amalgamation as we now are.
+automatically since it is part of the same amalgamation.
 
 Of course, \c{bpkg} has no idea \c{hello2} is now part of its configuration:
 
@@ -990,7 +993,7 @@ reason why we would want that: if we upgrade \c{libhello} we would want
 to remember and do it ourselves.
 
 The only way to make \c{bpkg} aware of \c{hello2} is to turn it from merely a
-\c{build2} \i{project} into a \c{bpkg} \i{package}. While the topic of
+\c{build2} \i{project} into a \c{build2} \i{package}. While the topic of
 packaging is also for another time and place (the \c{build2} package manager
 manual), we can get away with something as simple as this:
 
@@ -1021,7 +1024,8 @@ rmdir /tmp/hello-gcc5-release/hello2/
 
 Next, we use the \l{bpkg-pkg-build(1) \c{bpkg build}} command but instead of
 giving it a package name like we did before, we will point it to our \c{hello2}
-package directory:
+package directory (\c{bpkg} can fetch packages or it can build local package
+archives or package directories):
 
 \
 $ bpkg build -d /tmp/hello-gcc5-release/ ./hello2/
@@ -1050,20 +1054,7 @@ configured libformat/1.0.0
 configured libprint/1.0.0
 configured libhello/1.1.0
 configured hello2/1.0.0
-c++ libhello-1.1.0/hello/cxx{hello}
-c++ libprint-1.0.0/print/cxx{print}
-ld libprint-1.0.0/print/liba{print}
-c++ libformat-1.0.0/format/cxx{format}
-ld libformat-1.0.0/format/liba{format}
-ld libhello-1.1.0/hello/liba{hello}
-c++ libhello-1.1.0/hello/cxx{hello}
-c++ libprint-1.0.0/print/cxx{print}
-ld libprint-1.0.0/print/libs{print}
-c++ libformat-1.0.0/format/cxx{format}
-ld libformat-1.0.0/format/libs{format}
-ld libhello-1.1.0/hello/libs{hello}
-c++ libhello-1.1.0/tests/test/cxx{driver}
-ld libhello-1.1.0/tests/test/exe{driver}
+[ ... updating libprint, libformat, and libhello ... ]
 updated libhello/1.1.0
 \
 
@@ -1095,11 +1086,7 @@ added repository build2.org/hello/testing
 
 $ bpkg fetch
 fetching build2.org/hello/testing
-warning: authenticity of the certificate for repository build2.org/hello/testing cannot be established
-certificate is for build2.org, \"Code Synthesis\" <admin@build2.org>
-certificate SHA256 fingerprint:
-FF:DF:7D:38:67:4E:C3:82:65:7E:[...]:29:9A:30:56:B9:77:B9:F2:01:94
-trust this certificate? [y/N] y
+[... certificate authentication ...]
 fetching build2.org/hello/stable (complements build2.org/hello/testing)
 5 package(s) in 2 repository(s)
 
@@ -1119,7 +1106,7 @@ c++ libhello-1.0.0/hello/cxx{hello}
 ld libhello-1.0.0/hello/libs{hello}
 c++ libhello-1.0.0/tests/test/cxx{driver}
 ld libhello-1.0.0/tests/test/exe{driver}
-c++ path/to/hello2/cxx{hello}@hello2-1.0.0/
+c++ /path/to/hello2/cxx{hello}@hello2-1.0.0/
 ld hello2-1.0.0/exe{hello}
 updated libhello/1.0.0
 updated hello2/1.0.0
@@ -1163,7 +1150,7 @@ Hello, Windows!
 \
 
 In fact, on a properly setup GNU/Linux machine (that automatically uses
-\c{wine} as a \c{.exe} interpreter) we can even run tests:
+\c{wine} as an \c{.exe} interpreter) we can even run tests:
 
 \
 $ bpkg test libhello hello