Add note to bootstrap

1 files changed, 33 insertions, 2 deletions

diff --git a/bootstrap b/bootstrap
index 0458945..dbc1d7f 100755
--- a/bootstrap
+++ b/bootstrap
@@ -17,8 +17,8 @@
 #
 # 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 it would typically go to ~/work/{cli,odb/}, for
-#    example (for CLI; note: remove sanitizers for ODB):
+#    For the latter case they would typically go to ~/work/{cli,odb/}, for
+#    example (showing for CLI; note: remove sanitizers for ODB):
 #
 #    NOTE: clone using the git.codesynthesis.com:/var/scm/cli/cli.git SSH
 #          URL for rw access.
@@ -47,6 +47,37 @@
 #
 # 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 a 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). 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.
+#
 # Options:
 #
 # --ssh