diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 65 |
1 files changed, 56 insertions, 9 deletions
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). " |