diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/buildfile | 1 | ||||
| -rwxr-xr-x | doc/cli.sh | 7 | ||||
| -rw-r--r-- | doc/manual.cli | 58 | ||||
| m--------- | doc/style | 0 |
4 files changed, 51 insertions, 15 deletions
diff --git a/doc/buildfile b/doc/buildfile index 4b70658..5248576 100644 --- a/doc/buildfile +++ b/doc/buildfile @@ -1,5 +1,4 @@ # file : doc/buildfile -# copyright : Copyright (c) 2014-2019 Code Synthesis Ltd # license : TBC; see accompanying LICENSE file define css: file @@ -1,7 +1,6 @@ #! /usr/bin/env bash -version=0.13.0-a.0.z -date="$(date +"%B %Y")" +version=0.17.0-a.0.z trap 'exit 1' ERR set -o errtrace # Trap in functions. @@ -9,6 +8,9 @@ set -o errtrace # Trap in functions. function info () { echo "$*" 1>&2; } function error () { info "$*"; exit 1; } +date="$(date +"%B %Y")" +copyright="$(sed -n -re 's%^Copyright \(c\) (.+)\.$%\1%p' ../LICENSE | head -n 1)" + while [ $# -gt 0 ]; do case $1 in --clean) @@ -41,6 +43,7 @@ function compile_doc () # <file> <prefix> <suffix> cli -I .. \ -v version="$(echo "$version" | sed -e 's/^\([^.]*\.[^.]*\).*/\1/')" \ -v date="$date" \ +-v copyright="$copyright" \ --generate-html --html-suffix .xhtml \ --html-prologue-file doc-prologue.xhtml \ --html-epilogue-file doc-epilogue.xhtml \ diff --git a/doc/manual.cli b/doc/manual.cli index a2484aa..2852064 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -1,5 +1,4 @@ // file : doc/manual.cli -// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd // license : MIT; see accompanying LICENSE file "\name=build2-buildos-manual" @@ -182,23 +181,47 @@ sudo kvm \ A Build OS instances divides available CPUs and RAM (minus reserved, see below) into \i{slices} that are then \i{committed} to each instance of each -toolchain. If you don't expect your builds to utilize these resources at the -same time, then it may make sense to overcommit them to improve utilization. -The respective overcommit values can be specified as ratios with the -\c{buildos.cpu_overcommit} and \c{buildos.ram_overcommit} kernel command -line parameters. For example, given the following CPU overcommit: +toolchain. In case of CPU it normally makes sense to overcommit this resource +in order to improve utilization. This can be achieved by specifying the +overcommit values as a ratio with \c{buildos.cpu_overcommit}. For example, +given the following CPU overcommit: \ buildos.cpu_overcommit=3/2 \ -A Build OS machine with 8 CPUs (hardware threads) and three toolchains will +A Build OS machine with 8 CPUs (hardware threads) and three instances will assign 4 CPUs (\c{8 * 3/2 / 3}) to each slice. -It is also possible to reserve a number of CPUs and an amount of RAM to -Build OS with the \c{buildos.cpu_reserved} and \c{buildos.ram_reserved} -(in GB) kernel command line parameters. If unspecified, 4GB of RAM is -reserved by default. +It is also possible to specify CPU affinity with \c{buildos.cpu_affinity}. +For example, specifying: + +\ +buildos.cpu_affinity=2-9 +\ + +Will restrict the instances to only running on CPUs 2-9. + +It is possible to reserve a number of CPUs and an amount of RAM to Build OS +with the \c{buildos.cpu_reserved} and \c{buildos.ram_reserved} (in GiB) kernel +command line parameters. If unspecified, 4GiB of RAM is reserved by default. + +An amount of RAM can be reserved for auxiliary machines with +\c{buildos.ram_auxiliary}. This amount will also be divided into slices and +committed to each instance. + +Finally, if the total available RAM cannot be auto-detected, it can be +specified manually with \c{buildos.ram_total}. Here is a complete example of +specifying all the possible RAM values: + +\ +buildos.ram_total=64 +buildos.ram_reserved=4 +buildos.ram_auxiliary=12 +\ + +Assuming three instances, the configuration will assign 16GiB of build and +4GiB of auxiliary RAM to each instance and keep 4GiB reserved to Build OS. \h#config-storage|Storage| @@ -218,7 +241,7 @@ The stored state is fairly small (hundreds of megabytes) and is not performance-critical. While one can create a small state partition on the same physical disk as used for machines (see below), having it on a separate disk makes it easier to move machine disks around. Based on these requirements, a -small USB flash drive or flash card is a good option. +small, good-quality USB flash drive or flash card is a good option. While any suitable filesystem can be used, \c{ext4} is a good choice, with journaling disabled if used on a flash drive/card. For example: @@ -227,6 +250,11 @@ journaling disabled if used on a flash drive/card. For example: mkfs.ext4 -L buildos.state -O ^has_journal /dev/sdX \ +\N|Flash drives and cards tend to fail over time and while the state is not +precious, recreating it would also require updating the public key on all the +controllers that this build host serves. As a result, it may be prudent to +backup it up.| + \h2#config-storage-machines|Machines| For virtual machine and container storage we can use a single disk, in which @@ -276,6 +304,12 @@ confirm over-provisioning, format the disk as \c{btrfs}, and label it as # ^D # Exit shell and reboot. \ +To create a single \c{btrfs} disk that spans multiple physical devices: + +\ +# mkfs.btrfs -L buildos.machines -d single -m single /dev/sda /dev/sdb +\ + \h#config-net|Network| Network is configured via DHCP. Initially, all Ethernet interfaces that have diff --git a/doc/style b/doc/style -Subproject 7e75bb936cf5b2bd2fa3344e13b6c486c8ecc8a +Subproject b72eb624d13b1628e27e9f6c0b3c80853e8e015 |