Add comments

build-in-qemu.sh

 #!/bin/bash
+# build-in qemu.sh runs build.sh in a qemu VM running the latest Arch installer iso
+#
+# nounset: "Treat unset variables and parameters [...] as an error when performing parameter expansion."
+# errexit: "Exit immediately if [...] command exits with a non-zero status."
 set -o nounset -o errexit
 MIRROR="https://mirror.pkgbuild.com"
 
@@ -8,12 +12,14 @@ mkdir -p "tmp" "${OUTPUT}"
 TMPDIR="$(mktemp --directory --tmpdir="${PWD}/tmp")"
 cd "${TMPDIR}"
 
+# Do some cleanup when the script exits
 function cleanup() {
   rm -rf "${TMPDIR}"
   jobs -p | xargs --no-run-if-empty kill
 }
 trap cleanup EXIT
 
+# Use local Arch iso or download the latest iso and extract the relevant files
 function prepare_boot() {
   if LOCAL_ISO="$(ls "${ORIG_PWD}/"archlinux-*-x86_64.iso 2>/dev/null)"; then
     echo "Using local iso: ${LOCAL_ISO}"
@@ -30,11 +36,14 @@ function prepare_boot() {
     ISO="${PWD}/${LATEST_ISO}"
   fi
 
+  # We need to extract the kernel and initrd so we can set a custom cmdline:
+  # console=ttyS0, so the kernel and systemd sends output to the serial.
   xorriso -osirrox on -indev "${ISO}" -extract arch/boot/x86_64 .
   ISO_VOLUME_ID="$(xorriso -indev "${ISO}" |& awk -F : '$1 ~ "Volume id" {print $2}' | tr -d "' ")"
 }
 
 function start_qemu() {
+  # Used to communicate with qemu
   mkfifo guest.out guest.in
   # We could use a sparse file but we want to fail early
   fallocate -l 4G scratch-disk.img
@@ -54,13 +63,15 @@ function start_qemu() {
     -serial pipe:guest \
     -nographic || kill "${$}"; } &
 
-  # Send guest.out to fd1 (stdout) and fd10
+  # We want to send the output to both stdout (fd1) and fd10 (used by the expect function)
   exec 3>&1 10< <(tee /dev/fd/3 <guest.out)
 }
 
+# Wait for a specific string from qemu
 function expect() {
   length="${#1}"
   i=0
+  # We can't use ex: grep as we could end blocking forever, if the string isn't followed by a newline
   while IFS= read -r -u 10 -n 1 c; do
     if [ "${1:${i}:1}" = "${c}" ]; then
       i="$((i + 1))"
@@ -73,6 +84,7 @@ function expect() {
   done
 }
 
+# Send string to qemu
 function send() {
   echo -en "${1}" >guest.in
 }

build.sh

 #!/bin/bash
+# build.sh builds the images (cloud image, vagrant boxes)
+
+# nounset: "Treat unset variables and parameters [...] as an error when performing parameter expansion."
+# errexit: "Exit immediately if [...] command exits with a non-zero status."
 set -o nounset -o errexit
 DISK_SIZE="2G"
 IMAGE="image.img"
@@ -22,7 +26,9 @@ cd "${TMPDIR}"
 MOUNT="${PWD}/mount"
 mkdir "${MOUNT}"
 
+# Do some cleanup when the script exits
 function cleanup() {
+  # We want all the commands to run, even if one of them fails.
   set +o errexit
   if [ -n "${LOOPDEV:-}" ]; then
     losetup -d "${LOOPDEV}"
@@ -37,6 +43,7 @@ function cleanup() {
 }
 trap cleanup EXIT
 
+# Create the disk, partitions it, format the partition and mount the filesystem
 function setup_disk() {
   truncate -s "${DISK_SIZE}" "${IMAGE}"
   sgdisk --clear \
@@ -49,6 +56,7 @@ function setup_disk() {
   mount -o compress-force=zstd "${LOOPDEV}p2" "${MOUNT}"
 }
 
+# Install Arch Linux to the filesystem (bootstrap)
 function bootstrap() {
   cat <<EOF >pacman.conf
 [options]
@@ -70,6 +78,7 @@ EOF
   cp mirrorlist "${MOUNT}/etc/pacman.d/"
 }
 
+# Misc "tweaks" done after bootstrapping
 function postinstall() {
   arch-chroot "${MOUNT}" /usr/bin/btrfs subvolume create /swap
   chattr +C "${MOUNT}/swap"
@@ -83,6 +92,7 @@ function postinstall() {
   ln -sf /var/run/systemd/resolve/resolv.conf "${MOUNT}/etc/resolv.conf"
 }
 
+# Cleanup the image and trim it
 function image_cleanup() {
   # Remove machine-id: see https://github.com/archlinux/arch-boxes/issues/25
   rm "${MOUNT}/etc/machine-id"
@@ -94,6 +104,7 @@ function image_cleanup() {
   fstrim --verbose "${MOUNT}"
 }
 
+# Mount image helper (loop device + mount)
 function mount_image() {
   LOOPDEV=$(losetup --find --partscan --show "${1:-${IMAGE}}")
   mount -o compress-force=zstd "${LOOPDEV}p2" "${MOUNT}"
@@ -101,17 +112,20 @@ function mount_image() {
   mount --bind "/var/cache/pacman/pkg" "${MOUNT}/var/cache/pacman/pkg"
 }
 
+# Unmount image helper (umount + detach loop device)
 function unmount_image() {
   umount --recursive "${MOUNT}"
   losetup -d "${LOOPDEV}"
   LOOPDEV=""
 }
 
+# Copy image and mount the copied image
 function copy_and_mount_image() {
   cp -a "${IMAGE}" "${1}"
   mount_image "${1}"
 }
 
+# Compute SHA256, adjust owner to $SUDO_UID:$SUDO_UID and move to output/
 function mv_to_output() {
   sha256sum "${1}" >"${1}.SHA256"
   if [ -n "${SUDO_UID:-}" ]; then
@@ -120,6 +134,7 @@ function mv_to_output() {
   mv "${1}"{,.SHA256} "${OUTPUT}/"
 }
 
+# Helper function: create a new image from the "base" image
 # ${1} - new image file
 # ${2} - final file
 # ${3} - pre
@@ -144,6 +159,7 @@ function cloud_image_post() {
   rm "${1}"
 }
 
+# Create Vagrant box
 function create_box() {
   TYPE="${1}"
   IMAGE_FILE="${2}"