diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 56 |
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. |