From c82efc3e5ee4619e6ffc638911659b3dc184fdaf Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 29 Mar 2017 14:33:31 +0200
Subject: Implement toolchain fetching and monitoring

---
 doc/manual.cli | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 56 insertions(+), 9 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 04227f9..e61caa2 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -79,11 +79,16 @@ booted locally from the kernel image and initrd directly.
 
 \h#boot-reboot|Reboot|
 
-Build OS can detect when the OS build has been updated and automatically
-reboot the build host. This is achieved by polling the URL specified
-with the \c{buildos.buildid_url} kernel command line parameter. It should
-point to the \c{buildos-buildid} file that comes along the kernel image
-and initrd. See \l{#boot-net Network Boot} for the usage example.
+Build OS can detect when the OS or toolchain have been updated and
+automatically reboot the build host. This is achieved by polling the URLs
+specified with the \c{buildos.buildid_url} and \c{buildos.toolchain_url}
+kernel command line parameters.
+
+The \c{buildos.buildid_url} value should point to the \c{buildos-buildid} file
+that comes along the kernel image and initrd. The \c{buildos.toolchain_url}
+value is the location of the toolchain checksums file as described in
+\l{#config-toolchain Toolchain}. See \l{#boot-net Network Boot} for the usage
+example.
 
 \h#boot-net|Network Boot|
 
@@ -121,13 +126,14 @@ label buildos
   menu label buildos
   kernel /buildos/buildos-image
   initrd /buildos/buildos-initrd
-  append buildos.smtp_relay=example.org buildos.admin_email=admin@example.org buildos.buildid_url=tftp://<tftp-host>/buildos/buildos-buildid
+  append buildos.smtp_relay=example.org buildos.admin_email=admin@example.org buildos.buildid_url=tftp://<os-host>/buildos/buildos-buildid buildos.toolchain_url=https://<toolchain-host>/toolchain.sha256
 EOF
 \
 
-Where \c{<tftp-host>} in \c{buildid_url} is the address of the TFTP server
-(the same address as returned by the DHCP server to PXE clients). Note that
-all the parameters in \c{append} must be specified on a single line.|
+Where \c{<os-host>} is the address of the TFTP server (the same address as
+returned by the DHCP server to PXE clients) and \c{<toolchain-host>} is the
+host that serves the toolchain archives. Note that all the parameters in
+\c{append} must be specified on a single line.|
 
 \li|You can test the setup using QEMU/KVM, for example:
 
@@ -283,4 +289,45 @@ quotes):
 \
 buildos.ssh_key=\"ssh-rsa AAA...OA0DB user@host\"
 \
+
+\h#config-toolchain|Toolchain|
+
+The first step performed by the Build OS monitor is to bootstrap the
+\c{build2} toolchain. The location of the toolchain packages is specified with
+the \c{buildos.toolchain_url} kernel command line parameter. This URL should
+point to the \i{toolchain checksums file}.
+
+Each line in the checksums file is the output of the \c{shaNNNsum(1)} utility,
+that is, the SHANNN sum following by space, an asterisk (\c{*}) which signals
+the binary mode), and the relative file path. Blank lines and lines that start
+with \c{#} are ignored. The extension of the checksums file should be
+\c{.shaNNN} and the first entry should be for the \c{build2-toolchain} \c{tar}
+archive itself (used to derive the toolchain version). For example:
+
+\
+# toolchain.sha256
+ae89[...]87a4 *0.4.0/build2-toolchain-0.4.0.tar.xz
+058d[...]c962 *0.4.0/build2-baseutils-0.4.0-x86_64-windows.zip
+e723[...]c305 *0.4.0/build2-mingw-0.4.0-x86_64-windows.tar.xz
+\
+
+Based on the checksums file the monitor downloads each file into
+\c{/build/tftp/} (the file path is taken as relative to \c{toolchain_url}),
+verifies their checksums, and creates \i{predictable name} symlinks (names
+without the version). Continuing with the above example, the contents of
+\c{/build/tftp/} would be:
+
+\
+build2-toolchain-0.4.0.tar.xz
+build2-baseutils-0.4.0-x86_64-windows.zip
+build2-mingw-0.4.0-x86_64-windows.tar.xz
+
+build2-toolchain-tar.xz             -> build2-toolchain-0.4.0.tar.xz
+build2-baseutils-x86_64-windows.zip -> build2-baseutils-0.4.0-x86_64-windows.zip
+build2-mingw-x86_64-windows.tar.xz  -> build2-mingw-0.4.0-x86_64-windows.tar.xz
+\
+
+While the monitor itself only needs the \c{build2-toolchain} package, build
+machine toolchain bootstrap may require additional packages (which will be
+accessed via TFTP using predictable names).
 "
-- 
cgit v1.1