Update install & upgrade instructions with bdep information

6 files changed, 103 insertions, 72 deletions

diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli
index 8350b8d..400b61e 100644
--- a/BOOTSTRAP-MINGW.cli
+++ b/BOOTSTRAP-MINGW.cli
@@ -111,7 +111,8 @@ libraries statically.
 
 \li|\n\b{3. Stage}\n
 
-At this step the entire toolchain is built and staged:
+At this step the build system and package manager are built with shared
+libraries and then staged:
 
 \
 > cd ..  # Back to build2-toolchain-X.Y.Z\
@@ -122,7 +123,7 @@ At this step the entire toolchain is built and staged:
   config.install.root=C:\build2       ^
   config.install.data_root=root\stage
 
-> build2\build2\b-boot install
+> build2\build2\b-boot install: build2/ bpkg/
 \
 
 The strange-looking \c{config.install.data_root=root\\stage} means install
@@ -145,27 +146,29 @@ C:\build2\bin\bpkg-stage.exe
 > bpkg-stage --version
 \
 
-At the next step we will use \c{bpkg} to build and install the \"final\"
+At the next step we will use \c{bpkg} to build and install the entire
 toolchain. If for some reason you prefer not to build from packages (for
 example, because the machine is offline), then you can convert this step into
-the \"final\" installation and skip the rest. For this you will need to
-change the \c{configure} command line above along these lines:
+the \"final\" installation and skip the rest. For this you will need to change
+the \c{configure} and \c{install} command lines above along these lines:
 
 \
 > build2\build2\b-boot configure ^
   config.cxx=g++                 ^
   config.cc.coptions=-O3         ^
   config.install.root=C:\build2
+
+> build2\build2\b-boot install: build2/ bpkg/ bdep/
 \
 
 |
 
 \li|\n\b{4. 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.
+Next, we use the staged tools to build and install the entire toolchain from
+the package repository with 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\
@@ -184,8 +187,8 @@ Next, we add the package repository, build, and install:
 \
 > bpkg-stage add https://pkg.cppget.org/1/alpha
 > bpkg-stage fetch
-> bpkg-stage build --for install build2 bpkg
-> bpkg-stage install build2 bpkg
+> bpkg-stage build --for install build2 bpkg bdep
+> bpkg-stage install build2 bpkg bdep
 \
 
 Finally, we verify the result (note that the \c{where} command is not
@@ -198,19 +201,23 @@ C:\build2\bin\b.exe
 > where bpkg
 C:\build2\bin\bpkg.exe
 
+> where bdep
+C:\build2\bin\bdep.exe
+
 > b --version
 > bpkg --version
+> bdep --version
 \
 
 |
 
 \li|\n\b{5. Clean}\n
 
-The last thing we need to do is uninstall the staged toolchain:
+The last thing we need to do is uninstall the staged tools:
 
 \
 > cd ..\build2-toolchain-X.Y.Z  # Back to bootstrap.
-> b uninstall
+> b uninstall: build2/ bpkg/
 \
 
 ||
diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli
index c741f1e..7076deb 100644
--- a/BOOTSTRAP-MSVC.cli
+++ b/BOOTSTRAP-MSVC.cli
@@ -83,7 +83,8 @@ statically.
 
 \li|\n\b{3. Stage}\n
 
-At this step the entire toolchain is built and staged:
+At this step the build system and package manager are built with shared
+libraries and then staged:
 
 \
 > cd ..  # Back to build2-toolchain-X.Y.Z\
@@ -94,7 +95,7 @@ At this step the entire toolchain is built and staged:
   config.install.root=C:\build2       ^
   config.install.data_root=root\stage
 
-> build2\build2\b-boot install
+> build2\build2\b-boot install: build2/ bpkg/
 \
 
 The strange-looking \c{config.install.data_root=root\\stage} means install
@@ -117,27 +118,29 @@ C:\build2\bin\bpkg-stage.exe
 > bpkg-stage --version
 \
 
-At the next step we will use \c{bpkg} to build and install the \"final\"
+At the next step we will use \c{bpkg} to build and install the entire
 toolchain. If for some reason you prefer not to build from packages (for
 example, because the machine is offline), then you can convert this step into
-the \"final\" installation and skip the rest. For this you will need to
-change the \c{configure} command line above along these lines:
+the \"final\" installation and skip the rest. For this you will need to change
+the \c{configure} and \c{install} command lines above along these lines:
 
 \
 > build2\build2\b-boot configure ^
   config.cxx=cl                  ^
   \"config.cc.coptions=/O2 /Oi\"   ^
   config.install.root=C:\build2
+
+> build2\build2\b-boot install: build2/ bpkg/ bdep/
 \
 
 |
 
 \li|\n\b{4. 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.
+Next, we use the staged tools to build and install the entire toolchain from
+the package repository with 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\
@@ -156,8 +159,8 @@ Next, we add the package repository, build, and install:
 \
 > bpkg-stage add https://pkg.cppget.org/1/alpha
 > bpkg-stage fetch
-> bpkg-stage build --for install build2 bpkg
-> bpkg-stage install build2 bpkg
+> bpkg-stage build --for install build2 bpkg bdep
+> bpkg-stage install build2 bpkg bdep
 \
 
 Finally, we verify the result:
@@ -169,19 +172,23 @@ C:\build2\bin\b.exe
 > where bpkg
 C:\build2\bin\bpkg.exe
 
+> where bdep
+C:\build2\bin\bdep.exe
+
 > b --version
 > bpkg --version
+> bdep --version
 \
 
 |
 
 \li|\n\b{5. Clean}\n
 
-The last thing we need to do is uninstall the staged toolchain:
+The last thing we need to do is uninstall the staged tools:
 
 \
 > cd ..\build2-toolchain-X.Y.Z  # Back to bootstrap.
-> b uninstall
+> b uninstall: build2/ bpkg/
 \
 
 ||
diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli
index 40c70db..9e5b37d 100644
--- a/BOOTSTRAP-UNIX.cli
+++ b/BOOTSTRAP-UNIX.cli
@@ -152,9 +152,10 @@ $ build2/b-boot --version
 
 \li|\n\b{3. Stage}\n
 
-At 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).
+At this step the build system and package manager are built with shared
+libraries and then 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).
 
 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
@@ -173,7 +174,7 @@ $ build2/build2/b-boot configure      \
   config.install.data_root=root/stage \
   config.install.sudo=sudo
 
-$ build2/build2/b-boot install
+$ build2/build2/b-boot install build2/ bpkg/
 \
 
 The strange-looking \c{config.install.data_root=root/stage} means install
@@ -211,11 +212,11 @@ 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}.
 
-At the next step we will use \c{bpkg} to build and install the \"final\"
+At the next step we will use \c{bpkg} to build and install the entire
 toolchain. If for some reason you prefer not to build from packages (for
 example, because the machine is offline), then you can convert this step into
-the \"final\" installation and skip the rest. For this your will need to
-change the \c{configure} command line above along these lines:
+the \"final\" installation and skip the rest. For this you will need to change
+the \c{configure} and \c{install} command lines above along these lines:
 
 \
 $ build2/build2/b-boot configure  \
@@ -224,6 +225,8 @@ $ build2/build2/b-boot configure  \
   config.bin.rpath=/usr/local/lib \
   config.install.root=/usr/local  \
   config.install.sudo=sudo
+
+$ build2/build2/b-boot install: build2/ bpkg/ bdep/
 \
 
 |
@@ -231,10 +234,10 @@ $ build2/build2/b-boot configure  \
 
 \li|\n\b{4. 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.
+Next, we use the staged tools to build and install the entire toolchain from
+the package repository with 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/
@@ -255,8 +258,8 @@ Next, we add the package repository, build, and install:
 \
 $ bpkg-stage add https://pkg.cppget.org/1/alpha
 $ bpkg-stage fetch
-$ bpkg-stage build --for install build2 bpkg
-$ bpkg-stage install build2 bpkg
+$ bpkg-stage build --for install build2 bpkg bdep
+$ bpkg-stage install build2 bpkg bdep
 \
 
 Finally, we verify the result:
@@ -268,19 +271,23 @@ $ which b
 $ which bpkg
 /usr/local/bin/bpkg
 
+$ which bdep
+/usr/local/bin/bdep
+
 $ b --version
 $ bpkg --version
+$ bdep --version
 \
 
 |
 
 \li|\n\b{5. Clean}\n
 
-The last thing we need to do is uninstall the staged toolchain:
+The last thing we need to do is uninstall the staged tools:
 
 \
 $ cd ../build2-toolchain-X.Y.Z  # Back to bootstrap.
-$ b uninstall
+$ b uninstall: build2/ bpkg/
 \
 
 ||
diff --git a/INSTALL.cli b/INSTALL.cli
index 0c3ca27..fcdd440 100644
--- a/INSTALL.cli
+++ b/INSTALL.cli
@@ -46,26 +46,27 @@ able to rebuild the build system itself.|
 \li|\n\b{2. Bootstrap, Phase 2}\n
 
 Then, the build system is rebuilt with static libraries. The result is only
-guaranteed to be able to build the toolchain.|
+guaranteed to be able to build the build system and the package manager.|
 
 \li|\n\b{3. Stage}\n
 
-At this step the entire toolchain is built and staged.|
+At this step the build system and package manager are built with shared
+libraries and then staged.|
 
 \li|\n\b{4. Install}\n
 
-Next, the staged toolchain is used to build and install the \"final\"
-toolchain from the package repository and using the \c{bpkg} package manager.|
+Next, the staged tools are used to build and install the entire toolchain
+from the package repository with the \cb{bpkg} package manager.|
 
 \li|\n\b{5. Clean}\n
 
-Finally, the staged toolchain is uninstalled.||
+Finally, the staged at step 3 tools are uninstalled.||
 
 The end result of the bootstrap process is the installed toolchain as well as
 the \c{bpkg} configuration (created at step 4) that can be used to upgrade to
 newer versions. You can also skip step 4 and instead install at step 3 if for
-some reason you prefer not to use the package manager (for example, because
-the machine is offline).
+some reason you prefer not to build from packages (for example, because the
+machine is offline).
 
 
 For Windows, if you are using either MSVC or MinGW, continue with
diff --git a/README b/README
index f923c25..5f86f2a 100644
--- a/README
+++ b/README
@@ -1,6 +1,12 @@
 This is the build2 toolchain amalgamation. It includes the build system
-(build2), package manager (bpkg), and their prerequisite libraries (libbutl
-and libbpkg).
+(build2), package dependency manager (bpkg), project dependency manager
+(bdep), and their prerequisite libraries as subprojects.
+
+Note that while the MAJOR.MINIOR version components in the amalgamation and
+subprojects always match, the PATCH components are incremented more or less
+independently. Specifically, whenever a new patch release of a subproject is
+published, an updated amalgamation with an incremented PATCH component is
+released as well.
 
 build2 is an open source, cross-platform toolchain for building and packaging
 C++ code. Its aim is a modern build system and package manager for the C++
diff --git a/UPGRADE.cli b/UPGRADE.cli
index 9a9c1ac..01444d5 100644
--- a/UPGRADE.cli
+++ b/UPGRADE.cli
@@ -24,20 +24,20 @@ toolchain (similar to what we did during bootstrap), test it, uninstall the
 old toolchain, install the new toolchain as \"final\", and finally uninstall
 \c{-stage}.
 
-We recommend that you use a dirty upgrade for  bugfix-only releases (the same
-\c{X.Y} (\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.
+We recommend that you use a dirty upgrade for patch releases with the same
+\c{X.Y} (\c{MAJOR.MINOR}) version and a staged upgrade otherwise. With patch
+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:
+The dirty upgrade is straightforward:
 
 \
 $ cd build2-toolchain-X.Y
 $ bpkg fetch
-$ bpkg build --for install build2 bpkg
-$ bpkg install build2 bpkg
+$ bpkg build --for install build2 bpkg bdep
+$ bpkg install build2 bpkg bdep
 \
 
 You may also want to issue the \c{status} command after \c{fetch} to examine
@@ -46,10 +46,12 @@ 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 --for install build2/1.0.1 bpkg/1.0.1
+$ bpkg status build2 bpkg bdep
+!build2 configured 1.0.0 available 1.0.1 2.0.0
+!bpkg configured 1.0.0 available 1.0.1 2.0.0
+!bdep configured 1.0.0 available 1.0.1 2.0.0
+
+$ bpkg build --for install build2/1.0.1 bpkg/1.0.1 bdep/1.0.1
 \
 
 The staged upgrade consists of several steps:
@@ -66,7 +68,7 @@ version for the staged upgrade:
 \
 $ cd build2-toolchain-X.Y
 $ bpkg fetch
-$ bpkg status build2 bpkg
+$ bpkg status build2 bpkg bdep
 \
 
 Let's say the new version is X.Z.
@@ -95,15 +97,15 @@ Or, using Windows command prompt:
 \li|\n\b{2. Build and Install as \c{-stage}}\n
 
 This step is similar to the dirty upgrade except we use the copied
-configuration and install the toolchain with the \c{-stage} suffix:
+configuration and install the new toolchain with the \c{-stage} suffix:
 
 \
 $ cd build2-toolchain-X.Z
-$ bpkg build --for install build2 bpkg
+$ bpkg build --for install build2 bpkg bdep
 $ bpkg install                        \
   config.bin.suffix=-stage            \
   config.install.data_root=root/stage \
-  build2 bpkg
+  build2 bpkg bdep
 \
 
 |
@@ -111,12 +113,13 @@ $ bpkg install                        \
 \li|\n\b{3. Test Staged}\n
 
 Now you can 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}):
+\c{-stage}-suffixed binaries (\c{bdep-stage} will automatically use
+\c{bpkg-stage} which in turn will use \c{b-stage}):
 
 \
 $ b-stage --version
 $ bpkg-stage --version
+$ bdep-stage --version
 \
 
 |
@@ -128,10 +131,10 @@ one and install the new one:
 
 \
 $ cd ../build2-toolchain-X.Y
-$ bpkg uninstall build2 bpkg
+$ bpkg uninstall build2 bpkg bdep
 
 $ cd ../build2-toolchain-X.Z
-$ bpkg-stage install build2 bpkg
+$ bpkg-stage install build2 bpkg bdep
 \
 
 |
@@ -146,7 +149,7 @@ line history to find the corresponding \c{install} command and change it to
 $ bpkg uninstall                      \
   config.bin.suffix=-stage            \
   config.install.data_root=root/stage \
-  build2 bpkg
+  build2 bpkg bdep
 \
 
 You can also remove the old configuration in \c{build2-toolchain-X.Y/} if you