Add bootstrap protocol version to build machine directory names

1 files changed, 29 insertions, 27 deletions

diff --git a/doc/manual.cli b/doc/manual.cli
index e5f9b55..6648eec 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -351,7 +351,7 @@ accessed via TFTP using predictable names).
 
 \h1#machines|Build Machines|
 
-At the top level, a machine storage volume (\l{#config-storage-machines
+At the top level, a machine storage volume (see \l{#config-storage-machines
 Machines}) contains machine directories, for example:
 
 \
@@ -361,30 +361,32 @@ Machines}) contains machine directories, for example:
 \
 
 The layout inside a machine directory is as follows, where \c{<name>} is
-the machine name and \c{toolchain} is the toolchain name:
+the machine name and \c{<toolchain>} is the toolchain name:
 
 \
 <name>/
-├── <name>   -> <name>-2
-├── <name>-1/
-├── <name>-2/
+├── <name>-1   -> <name>-1.1
+├── <name>-1.0/
+├── <name>-1.1/
 ├── <name>-<toolchain>/
 └── <name>-<toolchain>-<xxx>/
 \
 
-The \c{<name>-<N>} entries are read-only \c{btrfs} subvolumes that contain
-the initial (that is, \i{pre-bootstrap}) machine images. The numeric \c{<N>}
-part indicate the machine revision.
+The \c{<name>-<P>.<R>} entries are read-only \c{btrfs} subvolumes that contain
+the initial (that is, \i{pre-bootstrap}) machine images. The numeric \c{<P>}
+part indicates the \i{bootstrap protocol version}. The numeric \c{<R>} part
+indicates the machine revision.
 
-The \c{<name>} entry is a symbolic link to the \c{<name>-<N>} that is
+The \c{<name>-<P>} entry is a symbolic link to \c{<name>-<P>.<N>} that is
 currently in effect.
 
 The \c{<name>-<toolchain>} entry is the bootstrapped machine image for
-\c{<toolchain>}. It is created by cloning \c{<name>} and then bootstrapping
+\c{<toolchain>}. It is created by cloning \c{<name>-<P>} with a bootstrap
+protocol version that matches this toolchain's \c{bbot} and then bootstrapping
 the \c{build2} toolchain inside.
 
 The \c{<name>-<toolchain>-<xxx>} entries are the temporary snapshots of
-\c{<name>-<toolchain>} created for building packages.
+\c{<name>-<toolchain>} created by \c{bbot} for building packages.
 
 A machine can be added, upgraded, or deleted on a live Build OS instance.
 This needs to be done in a particular order to avoid inconsistencies and race
@@ -392,7 +394,7 @@ conditions.
 
 \h#machines-add|Adding a Machine|
 
-Let's assume you have a read-only \c{btrfs} \c{linux-gcc_6-1} subvolume on a
+Let's assume you have a read-only \c{btrfs} \c{linux-gcc_6-1.0} subvolume on a
 development host (we will call it \c{devel}) that contains the initial version
 of our virtual machine. We would like to add it to the build host (running
 Build OS, we will call it \c{build}) into the default machine volume
@@ -406,26 +408,26 @@ build$ mkdir /build/machines/default/linux-gcc_6
 
 # Send the machine subvolume to build host.
 #
-devel$ sudo btrfs send linux-gcc_6-1 | \
+devel$ sudo btrfs send linux-gcc_6-1.0 | \
   ssh build@build sudo btrfs receive /build/machines/default/linux-gcc_6/
 
 build$ cd /build/machines/default/linux-gcc_6
 
 # Make user build the owner of the machine subvolume.
 #
-build$ sudo btrfs property set -ts linux-gcc_6-1 ro false
-build$ sudo chown build:build linux-gcc_6-1
-build$ btrfs property set -ts linux-gcc_6-1 ro true
+build$ sudo btrfs property set -ts linux-gcc_6-1.0 ro false
+build$ sudo chown build:build linux-gcc_6-1.0
+build$ btrfs property set -ts linux-gcc_6-1.0 ro true
 
 # Make the subvolume the current machine.
 #
-build$ ln -s linux-gcc_6-1 linux-gcc_6
+build$ ln -s linux-gcc_6-1.0 linux-gcc_6-1
 \
 
 \h#machines-upgade|Upgrading a Machine|
 
 Continuing with the example started in the previous section, let's assume we
-have created \c{linux-gcc_6-2} as a snapshot of \c{linux-gcc_6-1} and have
+have created \c{linux-gcc_6-1.1} as a snapshot of \c{linux-gcc_6-1.0} and have
 made some modification to the virtual machine (all on the development
 host). We now would like to switch to this new revision of our machine on the
 build host. To achieve this in an atomic way we perform the following steps:
@@ -433,26 +435,26 @@ build host. To achieve this in an atomic way we perform the following steps:
 \
 # Send the new machine subvolume to build host incrementally.
 #
-devel$ sudo btrfs send -p linux-gcc_6-1 linux-gcc_6-2 | \
+devel$ sudo btrfs send -p linux-gcc_6-1.0 linux-gcc_6-1.1 | \
   ssh build@build sudo btrfs receive /build/machines/default/linux-gcc_6/
 
 build$ cd /build/machines/default/linux-gcc_6
 
 # Make user build the owner of the new machine subvolume.
 #
-build$ sudo btrfs property set -ts linux-gcc_6-2 ro false
-build$ sudo chown build:build linux-gcc_6-2
-build$ btrfs property set -ts linux-gcc_6-2 ro true
+build$ sudo btrfs property set -ts linux-gcc_6-1.1 ro false
+build$ sudo chown build:build linux-gcc_6-1.1
+build$ btrfs property set -ts linux-gcc_6-1.1 ro true
 
 # Switch the current machine atomically.
 #
-build$ ln -s linux-gcc_6-2 new-linux-gcc_6
-build$ mv -T new-linux-gcc_6 linux-gcc_6
+build$ ln -s linux-gcc_6-1.1 new-linux-gcc_6-1
+build$ mv -T new-linux-gcc_6-1 linux-gcc_6-1
 
 # Remove the old machine subvolume (optional).
 #
-build$ btrfs property set -ts linux-gcc_6-1 ro false
-build$ btrfs subvolume delete linux-gcc_6-1
+build$ btrfs property set -ts linux-gcc_6-1.0 ro false
+build$ btrfs subvolume delete linux-gcc_6-1.0
 \
 
 \h#machines-delete|Deleting a Machine|
@@ -467,7 +469,7 @@ build$ cd /build/machines/default/linux-gcc_6
 
 # Delete the current machine symlink.
 #
-build$ rm linux-gcc_6
+build$ rm linux-gcc_6-1
 
 # Wait for all the linux-gcc_6-<toolchain>-<xxx> subvolumes
 # to disappear.