From 3aae83863801bc9608820afbaf32c2ed9f5ff29d Mon Sep 17 00:00:00 2001
From: Johannes Emerich <johannes@dividat.com>
Date: Wed, 24 Jul 2024 12:43:29 +0200
Subject: [PATCH] Update build/quick start instructions

The quick start instructions were actually more like "slow start"
instructions, suggesting to do a full build. Even worse, `nix build`
fails in modern versions of the Nix CLI, which expects to find a flake
file with this invocation.

This suggests to use the commonly used `./build` script instead and
updates it to provide a minimal bit of guidance when invoking it empty
(instead of doing, again, the full build).

A full build can still be done by invoking `./build all`.
---
 Readme.md | 39 +++++++++++++++++++++++----------------
 build     | 14 +++++++++++---
 2 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/Readme.md b/Readme.md
index 20c8fc0b..b7c6a9e3 100644
--- a/Readme.md
+++ b/Readme.md
@@ -21,18 +21,28 @@ This repository contains the application layer for running the Dividat Play web
 
 See the [documentation](docs/arch) and [user manual](docs/user-manual) for more information.
 
-## Quick start
+## Building the system
 
-Running `nix build` will create following (in `result/`):
+### Quick start
+
+The quickest way to see the system in action is to [use the QEMU VM](#qemu-vm).
+
+You can perform all common build variants using the `build` script. Run `./build` without parameters for a list of build variants.
+
+### Full build
+
+Running `./build all` (equivalently `nix-build`) creates all of the following (in `result/`):
 
 - `bin/`: Tools
 - `playos-VERSION-UNSIGNED.raucb`: RAUC bundle that can be used to update systems. Note that it is signed with a dummy development key. Real deployments would resign the bundle with `rauc resign`.
 - `playos-installer-VERSION.iso`: Bootable ISO image that can install the system.
 - `disk.img`: Preinstalled disk with bootloader, system partitions A/B and data partitions for testing (but without test instrumentation).
 
+Note that a full build takes a long time.
+
 ### Choose what to build
 
-For quicker development cycles you may pass following arguments to the build:
+The following arguments may be used to control the build outputs:
 
 - `buildInstaller`: Should the installer ISO image be built.
 - `buildBundle`: Should the RAUC bundle be built.
@@ -41,19 +51,6 @@ For quicker development cycles you may pass following arguments to the build:
 
 For example: `nix build --arg buildInstaller false --arg buildBundle false` will only build the system toplevels and the preinstalled disk image.
 
-A virtual machine (with test instrumentation) can be started without any of the above builds.
-
-## Components
-
-### Controller
-
-The [controller](controller/) service orchestrates the system's self-update and acts as a configuration interface for the options exposed to the user. It may be run directly on a Linux host for development purposes.
-
-### Kiosk
-
-The [kiosk](kiosk/) browser is used in the default configuration of PlayOS to run any web application in a full screen kiosk. It can be run directly on most hosts for development purposes.
-
-
 ## System Testing
 
 To test integrated portions of the PlayOS system, there are several options/levels available:
@@ -139,6 +136,16 @@ To release an update to the `develop` channel:
 
 When switching key pairs on a channel, the new certficiate must be built into the bundle, which must then be signed with the old key. For this purpose, the `--override-cert` option of the deploy script is needed to provide RAUC with a certificate matching the new key.
 
+## Components
+
+### Controller
+
+The [controller](controller/) service orchestrates the system's self-update and acts as a configuration interface for the options exposed to the user. It may be run directly on a Linux host for development purposes.
+
+### Kiosk
+
+The [kiosk](kiosk/) browser is used in the default configuration of PlayOS to run any web application in a full screen kiosk. It can be run directly on most hosts for development purposes.
+
 ## Change Log
 
 Update the change log for every release. See http://keepachangelog.com/ for formatting and conventions.
diff --git a/build b/build
index 0dc5aed2..1aed91e1 100755
--- a/build
+++ b/build
@@ -1,7 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-TARGET="${1:-default}"
+usage() {
+  echo "Usage: $0 {vm|develop|validation|master|stuck|lab-key|shed-key|all}"
+  exit 1
+}
+
+if [ $# -eq 0 ]; then
+  usage
+fi
+TARGET="$1"
 
 # Allow unfree packages, required for zerotier using a BSL 1.1 licence
 # See https://nixos.wiki/wiki/FAQ/How_can_I_install_a_proprietary_or_unfree_package%3F
@@ -106,7 +114,7 @@ elif [ "$TARGET" == "shed-key" ]; then
     --arg buildBundle false \
     --arg buildDisk false)
 
-elif [ "$TARGET" == "default" ]; then
+elif [ "$TARGET" == "all" ]; then
 
   (set -x; nix-build)
 
@@ -115,6 +123,6 @@ else
   echo
   echo "I do not know how to build '$TARGET'."
   echo "Aborting."
-  exit 1
+  usage
 
 fi