First take on new installation and upgrade instructions

16 files changed, 652 insertions, 382 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..68e3c03
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+INSTALL
+UPGRADE
+BOOTSTRAP-*
+!BOOTSTRAP-*.cli
diff --git a/BOOTSTRAP-MACOSX.cli b/BOOTSTRAP-MACOSX.cli
new file mode 100644
index 0000000..a60a145
--- /dev/null
+++ b/BOOTSTRAP-MACOSX.cli
@@ -0,0 +1,30 @@
+// file      : BOOTSTRAP-MACOSX.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+The \c{build2} toolchain requires Mac OS version 10.5 (Leopard) or later. We
+will also be using the system C++ toolchain that comes with the Xcode Command
+Line Tools (you should be able to use a custom C++ toolchain, however, this
+is the only configuration that is tested and guaranteed to work).
+
+To verify Command Line Tools are installed, run:
+
+\
+$ clang++ --version
+\
+
+It should produce something along these lines:
+
+\
+Apple LLVM version X.Y.Z (clang-A.B.C) (based on LLVM M.N.P)
+\
+
+To install Command Line Tools, run:
+
+\
+$ xcode-select --install
+\
+
+Once this is done continue with \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.
+"
diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
new file mode 100644
index 0000000..75a1c49
--- /dev/null
+++ b/BOOTSTRAP-MINGW.cli
@@ -0,0 +1,27 @@
+// file      : BOOTSTRAP-MINGW.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// 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
+specify an alternative package repository with the \c{BUILD2_REPO} environment
+variable.
+
+For example, if your MinGW distribution is in \c{C:\\mingw\\}, then you could
+run it (from the command prompt that we have started earlier) like this:
+
+\
+> build-mingw.bat C:\mingw\bin\g++
+\
+
+If you are using the \c{build2-mingw} package then you should be able to
+use just \c{g++} for the compiler:
+
+\
+> build-mingw.bat g++
+\
+"
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
new file mode 100644
index 0000000..36b666e
--- /dev/null
+++ b/BOOTSTRAP-MSVC.cli
@@ -0,0 +1,29 @@
+// file      : BOOTSTRAP-MSVC.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// 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:
+
+\
+> 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.
+
+For example, you could run thsi batch file (from the above-mentioned command
+prompt) like this:
+
+\
+> build-msvc.bat
+\
+"
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
new file mode 100644
index 0000000..864db7d
--- /dev/null
+++ b/BOOTSTRAP-UNIX.cli
@@ -0,0 +1,80 @@
+// file      : BOOTSTRAP-UNIX.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+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.
+
+\dl|
+
+\li|1. Create Build Directory\n
+
+Note that you will want to keep this directory around in order to upgrade to
+new toolchain versions in the future. In this guide we will use
+\c{~/build2-build/} as the build directory and \c{/usr/local/} as the
+installation directory but you can use other paths.
+
+\
+$ cd
+$ mkdir build2-build
+$ cd build2-build
+\
+
+|
+
+\li|\n2. Download, Verify, and Unpack\n
+
+Download \c{build2-toolchain-X.Y.Z.tar.xz} (or its \c{.tar.gz} variant if you
+don't have \cb{xz(1)}) as well as its \c{.sha256} checksum from
+\l{https://download.build2.org}, into \c{~/build2-build/} (build directory).
+
+Verify the archive checksum matches:
+
+\
+# Linux, MSYS, Cygwin:
+#
+$ sha256sum -c build2-toolchain-X.Y.Z.tar.xz.sha256
+
+# Mac OS X:
+#
+$ shasum -a 256 -c build2-toolchain-X.Y.Z.tar.xz.sha256
+
+# FreeBSD:
+#
+$ sha256 -r build2-toolchain-X.Y.Z.tar.xz
+$ cat build2-toolchain-X.Y.Z.tar.xz.sha256
+\
+
+Unpack the archive and change to its directory:
+
+\
+> tar xf build2-toolchain-X.Y.Z.tar.xz
+> cd build2-toolchain-X.Y.Z
+\
+
+||
+
+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.
+
+For example, this command will use \c{g++-5} and install the toolchain into
+\c{/usr/local/}.
+
+\
+$ build.sh g++-5
+\
+
+While this will use Clang and install into \c{/opt/build2}:
+
+\
+$ build.sh --install-dir /opt/build2 --sudo sudo clang++
+\
+"
diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli
new file mode 100644
index 0000000..872a10a
--- /dev/null
+++ b/BOOTSTRAP-WINDOWS.cli
@@ -0,0 +1,136 @@
+// file      : BOOTSTRAP-WINDOWS.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+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
+Bootstrapping on UNIX} instead.
+
+The \c{build2} toolchain on Windows requires a set of extra utilities
+(\c{install}, \c{diff}, \c{wget}, \c{tar}, etc). These are provided in the
+\c{build2-baseutils} package (see the \c{README} file inside for details).
+Normally the \c{build2} toolchain itself is installed into the same directory
+as the utilities in order to produce a combined \c{build2+utilities}
+installation.
+
+To build on Windows you will need either MSVC 14 Update 2 or later or MinGW
+GCC 4.8 or later. Note also that MinGW GCC must be configured with the
+\c{posix} threading model (this is currently the only configuration that
+implements C++11 threads; run \c{g++ --version} to verify).
+
+If you don't already have a suitable C++ compiler, then you can use the
+\c{build2-mingw} package which provides a minimal MinGW-W64 GCC distribution
+(see the \c{README} file inside for details). If used, then it should be
+unpacked into the same directory as \c{build2-baseutils} as described below.
+
+\dl|
+
+\li|1. Open Command Prompt\n
+
+Start the standard Windows Command Prompt. If you plan to build with MSVC,
+then you may go ahead and start the Visual Studio Command Prompt (or wait
+until MSVC-specific instructions).
+|
+
+\li|\n2. Create Build Directory\n
+
+Note that you will want to keep this directory around in order to upgrade
+to new toolchain versions in the future. In this guide we will use
+\c{C:\\build2-build\\} as the build directory and \c{C:\\build2\\} as the
+installation directory but you can use other paths.
+
+\
+> C:
+> cd \
+> mkdir build2-build
+> cd build2-build
+\
+
+|
+
+\li|\n3. Download Archives\n
+
+Download the following files as well as their \c{.sha256} checksums from
+\l{https://download.build2.org}, replacing \i{<arch>} with \c{x86_64} for
+64-bin Windows and with \c{i686} for 32-bit. Place everything into
+\c{C:\\build2-build\\} (build directory).
+
+\
+build2-baseutils-X.Y.Z-<arch>.zip
+build2-mingw-X.Y.Z-<arch>.tar.xz    (if required)
+build2-toolchain-X.Y.Z.tar.xz
+\
+
+|
+
+\li|\n4. Verify Archive Checksums\n
+
+Verify archive checksums match:
+
+\
+> type *.sha256
+> for %f in (*.zip *.xz) do certutil -hashfile %f SHA256
+\
+
+|
+
+\li|\n5. Unpack \c{build2-baseutils}\n
+
+Unpack the \c{build2-baseutils-X.Y.Z-<arch>.zip} archive into to \c{C:\\} using
+Windows Explorer (for example, copy the archive directory and paste it).
+Rename it to \c{C:\\build2\\}. This will be the toolchain installation
+directory.
+|
+
+\li|\n6. Set \c{PATH}\n
+
+Also verify the utilities are found and work:
+
+\
+> set PATH=C:\build2\bin;%PATH%
+> where tar
+> tar --version
+\
+
+|
+
+\li|\n7. Unpack \c{build2-mingw}\n
+
+If required, unpack the \c{build2-mingw-X.Y.Z-<arch>.tar.xz} archive into
+\c{C:\\build2\\}:
+
+\
+> tar xf build2-mingw-X.Y.Z-<arch>-windows.tar.xz ^
+  --one-top-level=C:\build2 --strip-components=1
+\
+
+Verify the MinGW GCC is found and works:
+
+\
+> where g++
+> g++ --version
+\
+
+|
+
+\li|\n8. Unpack \c{build2-toolchain}\n
+
+Unpack the \c{build2-toolchain-X.Y.Z.tar.xz} archive and change to its
+directory:
+
+\
+> tar xf build2-toolchain-X.Y.Z.tar.xz
+> cd build2-toolchain-X.Y.Z
+\
+
+||
+
+If building with MSVC, continue with \l{#BOOTSTRAP-MSVC Bootstrapping with
+MSVC}.
+
+If building with MinGW, continue with \l{#BOOTSTRAP-MINGW Bootstrapping with
+MINGW}.
+"
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 7c7516d..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,164 +0,0 @@
-The build2 toolchain requires a C++11 compiler with limited C++14 support. GCC
-4.8 or later and Clang 3.4 or later are known to work. If you only need the
-build2 build system without the bpkg package manager, then the C++ compiler is
-all you will need. If, however, you would also like to build bpkg, then you
-will also need to obtain SQLite as well as the libodb and libodb-sqlite
-libraries (discussed below).
-
-In this guide we install everything that we build into /usr/local. If you would
-like to use a different installation location, you will need to make
-adjustments to the commands below.
-
-Note on /usr/local: most distributions these days "cripple" this location by
-either not searching /usr/local/include for headers during compilation (so we
-add the -I option) or not searching /usr/local/lib for libraries either during
-linking (so we add the -L option) or at runtime (which we fix with the help of
--rpath). If you know that your installation doesn't suffer from (some of) these
-issues, then you can adjust the commands below accordingly. Note that even if
-/usr/local/lib is searched in at runtime, you may still have to run ldconfig(1)
-(as root) after the installation to refresh the library cache.
-
-Note to Mac OS users: you will need version 10.5 (Leopard) or later. We will
-also be using the system C++ toolchain that comes with the Xcode Command Line
-Tools. To verify it is installed, run:
-
-$ g++ --version
-
-To install Command Line Tools, run:
-
-$ xcode-select --install
-
-1. Installing SQLite
-
-    Skip this step if you are only interested in the build2 build system.
-
-    To install SQLite, use your distribution's package manager and make sure
-    you install both the libraries (most likely already installed) and the
-    development files.
-
-    For Debian/Ubuntu:
-
-    $ sudo apt-get install libsqlite3-dev
-
-    For RedHat/Fedora:
-
-    $ sudo yum install sqlite-devel
-
-    For FreeBSD:
-
-    # pkg install sqlite3
-
-    For Mac OS:
-
-    You should already have a system-default version installed. To verify:
-
-    $ ls /usr/include/sqlite3.h /usr/lib/libsqlite3.dylib
-
-    To see which version you have, run:
-
-    $ grep '#define SQLITE_VERSION' /usr/include/sqlite3.h
-
-    Any recent version (i.e., greater than 3.5.0) should work. If for some
-    reason you don't seem to have SQLite, download the source code then build
-    and install it into /usr/local.
-
-2. Installing libodb and libodb-sqlite
-
-    Again, skip this step if you are only interested in the build2 build
-    system.
-
-    [Currently we use pre-release versions of these libraries so they have to
-    be built from source.]
-
-    Download source packages for the two libraries from the same location as
-    build2-toolchain (https://download.build2.org). Then unpack, build, and
-    install:
-
-    $ cd lib*-X.Y.Z
-
-    $ ./configure --prefix=/usr/local \
-    CPPFLAGS=-I/usr/local/include     \
-    LDFLAGS=-L/usr/local/lib
-
-    $ make
-    $ sudo make install
-
-    See the INSTALL file for each library for more information.
-
-3. Bootstrapping build2
-
-    Download build2-toolchain (https://download.build2.org) then unpack and
-    bootstrap the build2 build system:
-
-    $ cd build2-toolchain-X.Y.Z
-    $ cd build2/
-    $ ./bootstrap
-    $ cd ..
-    $ ./build2/build2/b-boot build2/
-
-    For more information on this step (for example, how to specify the C++
-    compiler, options, etc.), refer to the INSTALL file in the build2/
-    subdirectory of build2-toolchain. Note that you must use global overrides
-    (!) if specifying any config.* variables on the last line. For example:
-
-    $ ./build2/build2/b-boot '!config.cxx=clang++' build2/
-
-4. Configuring, Building, and Installing the Rest of the Toolchain
-
-    $ ./build2/build2/b                      \
-    config.cxx.poptions=-I/usr/local/include \
-    config.cxx.loptions=-L/usr/local/lib     \
-    config.bin.rpath=/usr/local/lib          \
-    config.install.root=/usr/local           \
-    config.install.root.sudo=sudo            \
-    configure
-
-    $ ./build2/build2/b update
-    $ ./build2/build2/b install
-
-    To test the installation, run:
-
-    $ which b
-    /usr/local/bin/b
-    $ b --version
-
-    $ which bpkg
-    /usr/local/bin/bpkg
-    $ bpkg --version
-
-5. Setting up updates with the package manager
-
-    If you only need to build this specific version of the toolchain, then you
-    are done and can skip this step. However, if you are planning to upgrade to
-    future versions, then going every time through the bootstrap steps will be
-    tedious. Instead, we can use the bpkg package manager to manage upgrades
-    automatically. Note also that without periodic upgrades your version of the
-    toolchain may become too old to be able to upgrade itself. In this case you
-    will have to fall back onto the bootstrap process.
-
-    First, choose a directory where you would like bpkg to build everything,
-    for example, build2-toolchain. Then:
-
-    $ cd # back to home directory
-    $ mkdir build2-toolchain
-    $ cd build2-toolchain
-
-    $ bpkg create                             \
-    cxx                                       \
-    config.cxx.poptions=-I/usr/local/include  \
-    config.cxx.loptions=-L/usr/local/lib      \
-    config.bin.rpath=/usr/local/lib           \
-    config.install.root=/usr/local            \
-    config.install.root.sudo=sudo
-
-    $ bpkg add https://pkg.cppget.org/1/alpha
-    $ bpkg fetch
-    $ bpkg build build2 bpkg
-    $ bpkg install build2 bpkg
-
-    Later, to upgrade to a new version of the toolchain, simply do:
-
-    $ bpkg fetch
-    $ bpkg status build2 bpkg   # See if any upgrades are available.
-    $ bpkg build build2 bpkg
-    $ bpkg install build2 bpkg
diff --git a/INSTALL.cli b/INSTALL.cli
index 9a05afc..a8442fa 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -3,208 +3,68 @@
 // license   : MIT; see accompanying LICENSE file
 
 "
-The \c{build2} toolchain requires a C++11 compiler with limited C++14 support.
-GCC 4.8 or later and Clang 3.4 or later are known to work. If you only need the
-\c{build2} build system without the \c{bpkg} package manager, then the C++
-compiler is all you will need. If, however, you would also like to build
-\c{bpkg}, then you will also need to obtain SQLite as well as the \c{libodb}
-and \c{libodb-sqlite} libraries (discussed below).
-
-In this guide we install everything that we build into \c{/usr/local}. If you
-would like to use a different installation location, you will need to make
-adjustments to the commands below.
-
-Note on \c{/usr/local}: most distributions these days \"cripple\" this location
-by either not searching \c{/usr/local/include} for headers during compilation
-(so we add the \c{-I} option) or not searching \c{/usr/local/lib} for libraries
-either during linking (so we add the \c{-L} option) or at runtime (which we fix
-with the help of \c{-rpath}). If you know that your installation doesn't suffer
-from (some of) these issues, then you can adjust the commands below
-accordingly. Note that even if \c{/usr/local/lib} is searched in at runtime,
-you may still have to run \cb{ldconfig(1)} (as \c{root}) after the installation
-to refresh the library cache.
-
-Note to Mac OS users: you will need version 10.5 (Leopard) or later. We will
-also be using the system C++ toolchain that comes with the Xcode Command Line
-Tools. To verify it is installed, run:
-
-\
-$ g++ --version
-\
-
-To install Command Line Tools, run:
-
-\
-$ xcode-select --install
-\
+One of the primary goals of the \c{build2} toolchain is to provide a uniform
+build interface across all the platforms and compilers. If you already have
+the toolchain installed and would like to upgrade to a newer version, then
+there is a single set of \l{#UPGRADE upgrade instructions} for all the
+platforms.
+
+If, however, you need to install the toolchain for the first time, then it has
+to be bootstrapped and that process is platform-specific. The rest of this
+section discusses a few general bootstrap considerations and then directs
+you to appropriate platform-specific instructions.
+
+The \c{build2} toolchain requires a C++14 compiler. From the commonly-used
+options, GCC 4.8, Clang 3.4, and MSVC 2015/14 Update 2 or later
+versions are known to work. Note also that the C++ compiler that you use to
+build the \c{build2} toolchain and the one that you will use to build your
+projects need not be the same. For example, if you are using MSVC 2013/12
+(which cannot build \c{build2}), it is perfectly fine to get a minimal
+MinGW toolchain and use that to build \c{build2}; you will still be able
+to use MSVC to build your own projects.
+
+At the high level, the bootstrap process involves the following 5 steps.
 
 \dl|
 
-\li|1. Installing SQLite\n
+\li|1. Bootstrap, Phase 1\n
 
-    Skip this step if you are only interested in the \c{build2} build system.
+First, a minimal build system executable is built using provided shell
+scripts/batch files. The result is only guaranteed to be able to rebuild the
+build system itself.|
 
-    To install SQLite, use your distribution's package manager and make sure
-    you install both the libraries (most likely already installed) and the
-    development files.
+\li|\n2. Bootstrap, Phase 2\n
 
-    For Debian/Ubuntu:
+Then, the build system is rebuilt with static libraries. The result is only
+guaranteed to be able to build the toolchain.|
 
-    \
-    $ sudo apt-get install libsqlite3-dev
-    \
+\li|\n3. Stage\n
 
-    For RedHat/Fedora:
+On this step the entire toolchain is built and staged.|
 
-    \
-    $ sudo yum install sqlite-devel
-    \
+\li|\n4. Install\n
 
-    For FreeBSD:
+Next, the staged toolchain is used to build and install the toolchain from
+the package repository and using the \c{bpkg} package manager.|
 
-    \
-    # pkg install sqlite3
-    \
+\li|\n5. Clean\n
 
-    For Mac OS:
+Finally, the staged toolchain is uninstalled.||
 
-    You should already have a system-default version installed. To verify:
+The end result of the bootstrap process is the installed toolchain as well as
+the \c{bpkg} configuration (created on step 4) that can be used to upgrade to
+newer versions. You can also skip step 4 and instead install on step 3 if
+you would prefer not to use the package manager (for example, because the
+machine is offline).
 
-    \
-    $ ls /usr/include/sqlite3.h /usr/lib/libsqlite3.dylib
-    \
 
-    To see which version you have, run:
+For Windows, if using either MSVC or MinGW, continue with
+\l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}. If using MSYS or Cygwin,
+then instead refer to \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.
 
-    \
-    $ grep '#define SQLITE_VERSION' /usr/include/sqlite3.h
-    \
+For Mac OS X, continue with \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}.
 
-    Any recent version (i.e., greater than 3.5.0) should work. If for some
-    reason you don't seem to have SQLite, download the source code then build
-    and install it into \c{/usr/local}.
-
-    |
-
-\li|\n2. Installing \c{libodb} and \c{libodb-sqlite}\n
-
-   Again, skip this step if you are only interested in the \c{build2} build
-   system.
-
-   [Currently we use pre-release versions of these libraries so they have to be
-   built from source.]
-
-   Download source packages for the two libraries from the same location as
-   \l{https://download.build2.org \c{build2-toolchain}}. Then unpack, build,
-   and install:
-
-   \
-   $ cd lib*-X.Y.Z
-
-   $ ./configure --prefix=/usr/local \
-   CPPFLAGS=-I/usr/local/include     \
-   LDFLAGS=-L/usr/local/lib
-
-   $ make
-   $ sudo make install
-   \
-
-   See the \c{INSTALL} file for each library for more information.|
-
-\li|\n3. Bootstrapping \c{build2}\n
-
-   Download \l{https://download.build2.org \c{build2-toolchain}} then unpack
-   and bootstrap the \c{build2} build system:
-
-   \
-   $ cd build2-toolchain-X.Y.Z
-   $ cd build2/
-   $ ./bootstrap
-   $ cd ..
-   $ ./build2/build2/b-boot build2/
-   \
-
-   For more information on this step (for example, how to specify the C++
-   compiler, options, etc.), refer to the \c{INSTALL} file in the \c{build2/}
-   subdirectory of \c{build2-toolchain}. Note that you must use global
-   overrides (\c{!}) if specifying any \c{config.*} variables on the last
-   line. For example:
-
-   \
-   $ ./build2/build2/b-boot '!config.cxx=clang++' build2/
-   \
-
-   |
-
-\li|\n4. Configuring, Building, and Installing the Rest of the Toolchain\n
-
-   \
-   $ ./build2/build2/b                      \
-   config.cxx.poptions=-I/usr/local/include \
-   config.cxx.loptions=-L/usr/local/lib     \
-   config.bin.rpath=/usr/local/lib          \
-   config.install.root=/usr/local           \
-   config.install.root.sudo=sudo            \
-   configure
-
-   $ ./build2/build2/b update
-   $ ./build2/build2/b install
-   \
-
-   To test the installation, run:
-
-   \
-   $ which b
-   /usr/local/bin/b
-   $ b --version
-
-   $ which bpkg
-   /usr/local/bin/bpkg
-   $ bpkg --version
-   \
-
-   |
-
-\li|\n5. Setting up updates with the package manager\n
-
-   If you only need to build this specific version of the toolchain, then you
-   are done and can skip this step. However, if you are planning to upgrade to
-   future versions, then going every time through the bootstrap steps will be
-   tedious. Instead, we can use the \c{bpkg} package manager to manage upgrades
-   automatically. Note also that without periodic upgrades your version of the
-   toolchain may become too old to be able to upgrade itself. In this case you
-   will have to fall back onto the bootstrap process.
-
-   First, choose a directory where you would like \c{bpkg} to build everything,
-   for example, \c{build2-toolchain}. Then:
-
-   \
-   $ cd # back to home directory
-   $ mkdir build2-toolchain
-   $ cd build2-toolchain
-
-   $ bpkg create                             \
-   cxx                                       \
-   config.cxx.poptions=-I/usr/local/include  \
-   config.cxx.loptions=-L/usr/local/lib      \
-   config.bin.rpath=/usr/local/lib           \
-   config.install.root=/usr/local            \
-   config.install.root.sudo=sudo
-
-   $ bpkg add https://pkg.cppget.org/1/alpha
-   $ bpkg fetch
-   $ bpkg build build2 bpkg
-   $ bpkg install build2 bpkg
-   \
-
-   Later, to upgrade to a new version of the toolchain, simply do:
-
-   \
-   $ bpkg fetch
-   $ bpkg status build2 bpkg   # See if any upgrades are available.
-   $ bpkg build build2 bpkg
-   $ bpkg install build2 bpkg
-   \
-
-   ||
+For other UNIX-like operating systems (GNU/Linux, FreeBSD, etc; this also
+includes MSYS/Cygwin), continue with \l{#BOOTSTRAP-UNIX Bootstrapping on
+UNIX}.
 "
diff --git a/UPGRADE.cli b/UPGRADE.cli
new file mode 100644
index 0000000..5c07bf3
--- /dev/null
+++ b/UPGRADE.cli
@@ -0,0 +1,175 @@
+// file      : UPGRADE.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+At this point we assume that you have the build2 toolchain installed and would
+like to upgrade it to a newer version. We also expect that you have the
+toolchain \c{bpkg} configuration in the \c{build2-toolchain} directory, as
+produced by the bootstrap process. If you don't have the \c{bpkg}
+configuration but do have the toolchain installed somehow (for example, using
+your distribution's package manager), then you can create one as shown at the
+end. If you have neither, then you will need to go through the bootstrap
+process.
+
+There are two ways to upgrade: dirty (but quick) and staged (but more involved). In
+the \i{dirty upgrade} we override the existing installation without first
+uninstalling it. If some installed files no longer exist in the new version,
+they will remain \"installed\" until cleaned up manually.  Also, with this
+approach we never get a chance to make sure the new build is functional.
+
+In the \i{staged upgrade} we first install a \c{-stage} build of the new
+toolchain (similar to what we did during bootstrap), test it, uninstall the
+old toolchain, install the new toolchain as non-staged, and finally uninstall
+the \c{-stage} installation.
+
+We recommend that you use a dirty upgrade for a bugfix-only release (the same
+\c{MAJOR.MINOR} version) and a staged upgrade otherwise. With bugfix-only
+releases we guarantee not to alter the installation file set. Note also that
+without periodic upgrades your version of the toolchain may become too old to
+be able to upgrade itself. In this case you will have to fall back onto the
+bootstrap process.
+
+The dirty upgrade is fairly simple:
+
+\
+$ cd build2-toolchain
+$ bpkg fetch
+$ bpkg build build2 bpkg
+$ bpkg install build2 bpkg
+\
+
+You may also want to issue the \c{status} command after \c{fetch} to examine
+which versions are available. By default \c{bpkg} will upgrade to the latest
+available but you can override this by specifying the desired version
+explicitly, for example:
+
+\
+$ bpkg status build2 bpkg
+build2: configured 1.0.0; available 1.0.1 2.0.0
+bpkg: configured 1.0.0; available 1.0.1 2.0.0
+$ bpkg build build2/1.0.1 bpkg/1.0.1
+\
+
+The staged upgrade consists of several steps:
+
+\dl|
+
+\li|1. Save Old Configuration\n
+
+First we make a copy of the old configuration. We will need it later to
+cleanly uninstall the old toolchain.
+
+\
+$ rm -r build2-toolchain-old
+$ cp -r build2-toolchain build2-toolchain-old
+\
+
+Or, using Windows command prompt:
+
+\
+> rmdir /s /q build2-toolchain-old
+> xcopy /s /q /i build2-toolchain build2-toolchain-old
+\
+
+|
+
+\li|\n2. Build and Install as \c{-stage}\n
+
+This step is similar to the dirty upgrade except we install the toolchain with
+the \c{-stage} suffix.
+
+\
+$ cd build2-toolchain
+$ bpkg fetch
+$ bpkg build build2 bpkg
+$ bpkg install                        \
+  config.bin.suffix=-stage            \
+  config.install.data_root=root/stage \
+  build2 bpkg
+\
+
+|
+
+\li|\n3. Test Staged\n
+
+Now you can optionally test the new toolchain on your projects, etc. Remember
+to use the \c{-stage}-suffixed binaries (\c{bpkg-stage} will automatically use
+\c{b-stage}):
+
+\
+$ b-stage --version
+$ bpkg-stage --version
+\
+
+|
+
+\li|\n4. Uninstall Old, Install New\n
+
+Once we are satisfied the new toolchain works, we can uninstall the old
+one and install the new:
+
+\
+$ cd ../build2-toolchain-old
+$ bpkg uninstall build2 bpkg
+
+$ cd ../build2-toolchain
+$ bpkg-stage install build2 bpkg
+\
+
+|
+
+\li|\n5. Uninstall Staged\n
+
+Finally we clean up by removing the staged toolchain (hint: use command line
+history to find the corresponding \cb{install} command change it to
+uninstall):
+
+\
+$ bpkg uninstall                      \
+  config.bin.suffix=-stage            \
+  config.install.data_root=root/stage \
+  build2 bpkg
+\
+
+||
+
+If you ever need to (re-)create the \c{bpkg} configuration for the toolchain
+from scratch, it is fairly simple (you may need to adjust the compiler,
+options, installation directory, etc):
+
+For UNIX-like operating systems (GNU/Linux, Mac OS X, FreeBSD, etc):
+
+\
+$ 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
+\
+
+For Windows with MSVC (from the Visual Studio command prompt):
+
+\
+> bpkg-stage create              ^
+  cc                             ^
+  config.cxx=cl                  ^
+  \"config.cc.coptions=/O2 /Oi\"   ^
+  config.bin.lib=shared          ^
+  config.install.root=C:\build2
+\
+
+For Windows with MinGW (from the command prompt):
+
+\
+> bpkg-stage create             ^
+  cc                            ^
+  config.cxx=g++                ^
+  config.cc.coptions=-O3        ^
+  config.bin.lib=shared         ^
+  config.install.root=C:\build2
+\
+"
diff --git a/build/root.build b/build/root.build
index ac55324..b21d615 100644
--- a/build/root.build
+++ b/build/root.build
@@ -5,6 +5,16 @@
 # Load common modules that are used by subproject so that they use common
 # configuration.
 #
-using cxx.config
-using c.config
-using? cli.config
+using cxx
+using c
+
+# Load the cli module but only if it's available. This way a distribution
+# that includes pre-generated files can be built without installing cli.
+#
+using? cli
+
+if! $cli.configured
+{
+  define cli: file
+  cli{*}: extension = cli
+}
diff --git a/buildfile b/buildfile
index 26b18e6..ccc2f78 100644
--- a/buildfile
+++ b/buildfile
@@ -3,10 +3,22 @@
 # license   : MIT; see accompanying LICENSE file
 
 d = libbutl/ build2/ libsqlite3/ libodb/ libodb-sqlite/ libbpkg/ bpkg/ doc/
-./: $d doc{INSTALL README version} file{INSTALL.cli} \
+
+i =               \
+INSTALL           \
+UPGRADE           \
+BOOTSTRAP-MACOSX  \
+BOOTSTRAP-MINGW   \
+BOOTSTRAP-MSVC    \
+BOOTSTRAP-UNIX    \
+BOOTSTRAP-WINDOWS
+
+./: $d doc{$i README version} cli{$i} \
 file{build.sh build-msvc.bat build-mingw.bat}
+
 include $d
 
-# Don't install the INSTALL file.
+# Don't install the BOOTSTRAP/INSTALL files. But UPGRADE could be useful.
 #
 doc{INSTALL}@./: install = false
+doc{BOOTSTRAP-*}: install = false
diff --git a/doc/.gitignore b/doc/.gitignore
index 4bb8225..585f985 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,3 +1,3 @@
-build2-toolchain-intro*.ps
-build2-toolchain-intro*.pdf
-build2-toolchain-intro.xhtml
+build2-toolchain-*.ps
+build2-toolchain-*.pdf
+build2-toolchain-*.xhtml
diff --git a/doc/buildfile b/doc/buildfile
index fb23206..6914d41 100644
--- a/doc/buildfile
+++ b/doc/buildfile
@@ -5,12 +5,13 @@
 define css: file
 css{*}: extension = css
 
-./: doc{build2-toolchain-intro.xhtml               \
-        build2-toolchain-intro-a4.pdf              \
-        build2-toolchain-intro-a4.ps               \
-        build2-toolchain-intro-letter.pdf          \
-        build2-toolchain-intro-letter.ps}          \
-    css{code-box common doc pre-box toc}           \
-    file{a4.html2ps letter.html2ps doc.html2ps}    \
-    file{doc-prologue.xhtml doc-epilogue.xhtml     \
-         intro.cli cli.sh}
+intr = build2-toolchain-intro
+inst = build2-toolchain-install
+
+./: \
+doc{$(intr).xhtml $intr-a4.pdf $intr-a4.ps $intr-letter.pdf $intr-letter.ps} \
+doc{$(inst).xhtml $inst-a4.pdf $inst-a4.ps $inst-letter.pdf $inst-letter.ps} \
+css{code-box common doc pre-box toc}                                         \
+file{a4.html2ps letter.html2ps doc.html2ps}                                  \
+file{doc-prologue.xhtml doc-epilogue.xhtml}                                  \
+cli{intro.cli install.cli} file{cli.sh}
diff --git a/doc/cli.sh b/doc/cli.sh
index c9a3c8e..a376fad 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -13,7 +13,9 @@ while [ $# -gt 0 ]; do
   case $1 in
     --clean)
       rm -f build2-toolchain-intro.xhtml build2-toolchain-intro*.ps \
-build2-toolchain-intro*.pdf
+ build2-toolchain-intro*.pdf
+      rm -f build2-toolchain-install.xhtml build2-toolchain-install*.ps \
+build2-toolchain-install*.pdf
       exit 0
       ;;
     *)
@@ -22,16 +24,42 @@ build2-toolchain-intro*.pdf
   esac
 done
 
-cli -I .. -v version="$version" -v date="$date" \
+function gen () # <name>
+{
+  local n="$1"
+  shift
+  cli -I .. -v version="$version" -v date="$date" \
 --generate-html --html-suffix .xhtml \
 --html-prologue-file doc-prologue.xhtml \
 --html-epilogue-file doc-epilogue.xhtml \
---link-regex '%b([-.].+)%../../build2/doc/b$1%' \
---link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$1%' \
---output-prefix build2-toolchain- intro.cli
+--link-regex '%b([-.].+)%../../build2/doc/b$n%' \
+--link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$n%' \
+--output-prefix build2-toolchain- "${@}" $n.cli
 
-html2ps -f doc.html2ps:a4.html2ps -o build2-toolchain-intro-a4.ps build2-toolchain-intro.xhtml
-ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true build2-toolchain-intro-a4.ps build2-toolchain-intro-a4.pdf
+html2ps -f doc.html2ps:a4.html2ps -o build2-toolchain-$n-a4.ps build2-toolchain-$n.xhtml
+ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-a4.ps build2-toolchain-$n-a4.pdf
 
-html2ps -f doc.html2ps:letter.html2ps -o build2-toolchain-intro-letter.ps build2-toolchain-intro.xhtml
-ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-intro-letter.ps build2-toolchain-intro-letter.pdf
+html2ps -f doc.html2ps:letter.html2ps -o build2-toolchain-$n-letter.ps build2-toolchain-$n.xhtml
+ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-letter.ps build2-toolchain-$n-letter.pdf
+}
+
+# Auto-heading doesn't work since it is broken into multiple doc strings.
+#
+gen install --html-heading-map 2=h2
+gen intro
+
+# Generate INSTALL/BOOTSTRAP/UPGRADE file in ../
+#
+function gen_txt () # <name>
+{
+  cli --generate-txt --omit-link-check --link-regex '%#(.*)%\1 file%' \
+-o .. --txt-suffix "" ../$1.cli
+}
+
+gen_txt INSTALL
+gen_txt UPGRADE
+gen_txt BOOTSTRAP-MACOSX
+gen_txt BOOTSTRAP-MINGW
+gen_txt BOOTSTRAP-MSVC
+gen_txt BOOTSTRAP-UNIX
+gen_txt BOOTSTRAP-WINDOWS
diff --git a/doc/install.cli b/doc/install.cli
new file mode 100644
index 0000000..f8042f7
--- /dev/null
+++ b/doc/install.cli
@@ -0,0 +1,47 @@
+// file      : doc/install.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"\name=build2-toolchain-install"
+"\subject=toolchain"
+"\title=Toolchain Installation and Upgrade"
+
+// NOTES
+//
+// - Maximum <pre> line is 70 characters.
+//
+
+"
+\h#INSTALL|Introduction|
+"
+source "../INSTALL.cli";
+
+"
+\h#BOOTSTRAP-WINDOWS|Bootstrapping on Windows|
+"
+source "../BOOTSTRAP-WINDOWS.cli";
+
+"
+\h2#BOOTSTRAP-MSVC|Bootstrapping with MSVC|
+"
+source "../BOOTSTRAP-MSVC.cli";
+
+"
+\h2#BOOTSTRAP-MINGW|Bootstrapping with MINGW|
+"
+source "../BOOTSTRAP-MINGW.cli";
+
+"
+\h#BOOTSTRAP-MACOSX|Bootstrapping on Mac OS X|
+"
+source "../BOOTSTRAP-MACOSX.cli";
+
+"
+\h#BOOTSTRAP-UNIX|Bootstrapping on UNIX|
+"
+source "../BOOTSTRAP-UNIX.cli";
+
+"
+\h#UPGRADE|Upgrading|
+"
+source "../UPGRADE.cli";
diff --git a/doc/intro.cli b/doc/intro.cli
index e9782a3..791394c 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -1039,8 +1039,3 @@ $ wine hello-1.0.0/hello.exe Windows
 Hello, Windows!
 \
 "
-
-"
-\h#install|Installation|
-"
-source "../INSTALL.cli";