diff options
| -rw-r--r-- | .gitmodules | 3 | ||||
| -rw-r--r-- | README | 41 | ||||
| -rw-r--r-- | doc/.gitignore | 3 | ||||
| l--------- | doc/a4.html2ps | 1 | ||||
| -rwxr-xr-x | doc/cli.sh | 49 | ||||
| l--------- | doc/code-box.css | 1 | ||||
| l--------- | doc/common.css | 1 | ||||
| l--------- | doc/doc-epilogue.xhtml | 1 | ||||
| l--------- | doc/doc-prologue.xhtml | 1 | ||||
| l--------- | doc/doc.css | 1 | ||||
| l--------- | doc/doc.html2ps | 1 | ||||
| l--------- | doc/letter.html2ps | 1 | ||||
| -rw-r--r-- | doc/manual.cli | 117 | ||||
| l--------- | doc/pre-box.css | 1 | ||||
| m--------- | doc/style | 0 | ||||
| l--------- | doc/toc.css | 1 |
16 files changed, 195 insertions, 28 deletions
diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..144e9f5 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "doc/style"] + path = doc/style + url = ../etc/style.git @@ -1,35 +1,20 @@ -buildos is a Debian-based in-memory, net-booted operating system specialized -for building software with the build2 toolchain. +This package contains the build2 operating system bootstrap scripts. -Configuration -------------- +build2 is an open source, cross-platform toolchain for building and packaging +C++ code. Its aim is a modern build system and package manager for the C++ +language that provide a consistent, out of the box interface across multiple +platforms and compilers. For more information see: -- Network is configured via DHCP. All Ethernet intrface that have carrier are - tried in (some) order and the first interface that is successfully configure - via DHCP is used. +https://build2.org/ -- Hostname is configure from the DHCP information. Failed that, a name is - generated based on the MAC address. @@ Maybe also kernel cmdline. +See the NEWS file for the user-visible changes from the previous release. -PXE ---- +See the LICENSE file for the distribution conditions. -- Copy the kernel image and initrd to TFTP +See the INSTALL file for the prerequisites and installation instructions. -# mkdir -p /var/lib/tftpboot/buildos -# cp buildos-image buildos-initrd /var/lib/tftpboot/buildos/ +See the doc/ directory for documentation. -- Assuming the host has MAC address de-ad-be-ef-b8-da, create host-specific - configuration (or use 'default' for the last path component to apply to - all the hosts): - -# cat <<EOF >/var/lib/tftpboot/pxelinux.cfg/01-de-ad-be-ef-b8-da -default buildos -prompt 1 -timeout 50 - -label buildos - menu label buildos - kernel /buildos/buildos-image - append initrd=/buildos/buildos-initrd -EOF +Send questions, bug reports, or any other feedback to the users@build2.org +mailing list. You can post without subscribing. See https://lists.build2.org +for searchable archives, posting guidelines, etc. diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..5dddec7 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,3 @@ +build2-*-manual.xhtml +*.ps +*.pdf diff --git a/doc/a4.html2ps b/doc/a4.html2ps new file mode 120000 index 0000000..4b31c06 --- /dev/null +++ b/doc/a4.html2ps @@ -0,0 +1 @@ +style/a4.html2ps
\ No newline at end of file diff --git a/doc/cli.sh b/doc/cli.sh new file mode 100755 index 0000000..a658c3b --- /dev/null +++ b/doc/cli.sh @@ -0,0 +1,49 @@ +#! /usr/bin/env bash + +version="0.5.0" +date="January 2017" + +trap 'exit 1' ERR +set -o errtrace # Trap in functions. + +function info () { echo "$*" 1>&2; } +function error () { info "$*"; exit 1; } + +while [ $# -gt 0 ]; do + case $1 in + --clean) + rm -f build2-buildos-manual.xhtml + rm -f *.ps *.pdf + exit 0 + ;; + *) + error "unexpected $1" + ;; + esac +done + +# Manuals. +# + +function compile_doc () # <file> <prefix> <suffix> +{ + cli -I .. \ +-v version="$(echo "$version" | sed -e 's/^\([^.]*\.[^.]*\).*/\1/')" \ +-v date="$date" \ +--generate-html --html-suffix .xhtml \ +--html-prologue-file doc-prologue.xhtml \ +--html-epilogue-file doc-epilogue.xhtml \ +--output-prefix "$2" \ +--output-suffix "$3" \ +"$1" + + local n="$2$(basename -s .cli $1)$3" + + html2ps -f doc.html2ps:a4.html2ps -o "$n-a4.ps" "$n.xhtml" + ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true "$n-a4.ps" "$n-a4.pdf" + + html2ps -f doc.html2ps:letter.html2ps -o "$n-letter.ps" "$n.xhtml" + ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true "$n-letter.ps" "$n-letter.pdf" +} + +compile_doc manual.cli 'build2-buildos-' diff --git a/doc/code-box.css b/doc/code-box.css new file mode 120000 index 0000000..e442993 --- /dev/null +++ b/doc/code-box.css @@ -0,0 +1 @@ +style/code-box.css
\ No newline at end of file diff --git a/doc/common.css b/doc/common.css new file mode 120000 index 0000000..3ddf6fc --- /dev/null +++ b/doc/common.css @@ -0,0 +1 @@ +style/common.css
\ No newline at end of file diff --git a/doc/doc-epilogue.xhtml b/doc/doc-epilogue.xhtml new file mode 120000 index 0000000..5111ca2 --- /dev/null +++ b/doc/doc-epilogue.xhtml @@ -0,0 +1 @@ +style/doc-epilogue.xhtml
\ No newline at end of file diff --git a/doc/doc-prologue.xhtml b/doc/doc-prologue.xhtml new file mode 120000 index 0000000..e1fd108 --- /dev/null +++ b/doc/doc-prologue.xhtml @@ -0,0 +1 @@ +style/doc-prologue.xhtml
\ No newline at end of file diff --git a/doc/doc.css b/doc/doc.css new file mode 120000 index 0000000..6cb3fd5 --- /dev/null +++ b/doc/doc.css @@ -0,0 +1 @@ +style/doc.css
\ No newline at end of file diff --git a/doc/doc.html2ps b/doc/doc.html2ps new file mode 120000 index 0000000..dc19855 --- /dev/null +++ b/doc/doc.html2ps @@ -0,0 +1 @@ +style/doc.html2ps
\ No newline at end of file diff --git a/doc/letter.html2ps b/doc/letter.html2ps new file mode 120000 index 0000000..607ca58 --- /dev/null +++ b/doc/letter.html2ps @@ -0,0 +1 @@ +style/letter.html2ps
\ No newline at end of file diff --git a/doc/manual.cli b/doc/manual.cli new file mode 100644 index 0000000..22cbd13 --- /dev/null +++ b/doc/manual.cli @@ -0,0 +1,117 @@ +// file : doc/manual.cli +// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +"\name=build2-buildos-manual" +"\subject=buildos" +"\title=Operating System" + +// NOTES +// +// - Maximum <pre> line is 70 characters. +// + +" +\h0#preface|Preface| + +This document describes \c{buildos}, the \c{build2} operating system. + +\h1#intro|Introduction| + +\c{buildos} is a GNU/Linux(Debian)-based in-memory network-booted operating +system specialized for autonomous building of software using the \c{build2} +toolchain. It's primary purpose is to run the \c{build2} build bot (\c{bbot}), +build slave (\c{bslave}), or both. + +A machine that run an instance of \c{buildos} is called a \i{build host}. A +build host runs the \c{bbot} and/or \c{bslave} in the \i{agent mode}. The +actual building is performed in the virtual machines and/or containers. For +\c{bbot} it is normally one-shot virtual machines and for \c{bslave} it is +normally containers but can also be long-running virtual machines. Inside +virtual machines/containers, \c{bbot} and \c{bslave} run in the \i{worker +mode} and receive \i{build tasks} from their respective agents. + +\h1#boot|Booting| + +\c{buildos} is normally booted from the network using PXE but can also be +booted locally from initrd directly. + +\h2#boot-net|Network| + +Here we assume that you have already established your PXE setup using +PXELINUX. That is, you have configured a TFTP server that hosts the +\c{pxelinux} initial bootstrap program (NBP) and configured a DHCP +server to direct PXE client to this server/NBP. + +To setup PXE boot of \c{buildos}, perform the following steps: + +\ol| + +\li|Copy the kernel image and initrd to the TFTP server. For example: + +\ +# mkdir -p /var/lib/tftpboot/buildos +# cp buildos-image buildos-initrd /var/lib/tftpboot/buildos/ +\ + +| + +\li|Assuming the host has MAC address \c{de:ad:be:ef:b8:da}, create a + host-specific configuration file (or use \c{default} as the last path + component for a configuration that applies to all the hosts): + +\ +# cat <<EOF >/var/lib/tftpboot/pxelinux.cfg/01-de-ad-be-ef-b8-da +default buildos +prompt 1 +timeout 50 + +label buildos + menu label buildos + kernel /buildos/buildos-image + append initrd=/buildos/buildos-initrd +EOF +\ + +| + +\li|You can test the setup using QEMU/KVM, for example: + +\ +$ sudo kvm \ + -m 8G \ + -netdev tap,id=net0,script=./qemu-ifup \ + -device e1000,netdev=net0,mac=de:ad:be:ef:b8:da \ + -boot n +\ + +|| + +\h2#boot-local|Local| + +During testing it is often useful to boot \c{buildos} directly from the +kernel image and initrd files. As an example, here is how this can be done +using QEMU/KVM: + +\ +sudo kvm \ + -m 8G \ + -netdev tap,id=net0,script=./qemu-ifup \ + -device e1000,netdev=net0,mac=de:ad:be:ef:b8:da \ + -kernel buildos-image -initrd buildos-initrd +\ + +\h1#config|Configuration| + +\h2#config-net|Network| + +Network is configured via DHCP. All Ethernet intrface that have carrier are +tried in (some) order and the first interface that is successfully configured +via DHCP is used. + +Hostname is configured from the DHCP information. Failed that, a name is +generated based on the MAC address, in the form \c{build-xxxxxxxxxx}. + +@@ Maybe also kernel cmdline. + +" diff --git a/doc/pre-box.css b/doc/pre-box.css new file mode 120000 index 0000000..b9ec76c --- /dev/null +++ b/doc/pre-box.css @@ -0,0 +1 @@ +style/pre-box.css
\ No newline at end of file diff --git a/doc/style b/doc/style new file mode 160000 +Subproject 6afac719afc627d4c74dfbaa282b049f6f96e90 diff --git a/doc/toc.css b/doc/toc.css new file mode 120000 index 0000000..477b331 --- /dev/null +++ b/doc/toc.css @@ -0,0 +1 @@ +style/toc.css
\ No newline at end of file |