Merge branch 'qemu-virtiofsd' into 'master'

share host directories with Redox from 'make qemu' and add Cloud Hypervisor

See merge request redox-os/redox!2383

Makefile

@@ -96,8 +96,10 @@ include mk/repo.mk
 include mk/disk.mk
 
 # Emulation recipes
+include mk/virtiofs.mk
 include mk/qemu.mk
 include mk/virtualbox.mk
+include mk/ch.mk
 
 # CI
 include mk/ci.mk

mk/ch.mk

@@ -0,0 +1,162 @@
+# Configuration file for Cloud Hypervisor
+#
+#   make ch                  # boot $(DISK), serial console on this terminal
+#   make ch share=...        # also share host directories, see mk/virtiofs.mk
+#   make ch net=tap          # use the tap device $(CH_TAP) instead of passt
+#   make ch net=no           # no network device
+#   make ch-shutdown         # stop the VM, from another terminal
+#   make ch-fetch            # only download Cloud Hypervisor and its firmware
+#
+# x86_64 only. The guest boots through the CLOUDHV.fd UEFI firmware
+# (https://github.com/cloud-hypervisor/edk2/releases). The disks are virtio-blk.
+#
+# Cloud Hypervisor (cloud-hypervisor-static, ch-remote-static) and the firmware
+# are pinned below. They are downloaded on first use into
+# build/cloud-hypervisor/$(ARCH) and checked against their sha256. Set CH,
+# CH_REMOTE or CH_FIRMWARE to use other files, e.g. CH=cloud-hypervisor for
+# the one in PATH.
+#
+# The serial console puts this terminal in raw mode, so Ctrl-C goes to Redox.
+# Redox cannot power off Cloud Hypervisor by itself yet: use make ch-shutdown.
+#
+# The network is passt by default: a user-mode network stack, started by
+# scripts/passt-run.sh, that answers the guest's DHCP and DNS and carries its
+# traffic through ordinary host sockets. No tap, root or firewall changes are
+# needed. The guest gets the host's address, and nothing reaches it from
+# outside unless forwarded. CH_PASST_FLAGS passes options to passt, e.g.
+# "-t 8022:22" (host port 8022 to guest port 22) or
+# "--pcap $XDG_RUNTIME_DIR/redox.pcap" (capture the traffic).
+#
+# net=tap uses the tap device $(CH_TAP) instead: a real link that the host
+# can reach on any port and watch with tcpdump. Creating it needs root:
+# scripts/ch-tap-setup.sh (firewalld only) creates it and makes the host
+# the guest's DHCP server and NAT gateway.
+
+# Pinned releases. To update one, change its version and the sha256 of its
+# assets, which GitHub shows next to each file on the release page. Every
+# version is downloaded into its own directory.
+CH_VERSION=v54.0
+CH_FIRMWARE_VERSION=ch-97eeb7b09
+CH_URL=https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/$(CH_VERSION)
+CH_FIRMWARE_URL=https://github.com/cloud-hypervisor/edk2/releases/download/$(CH_FIRMWARE_VERSION)
+CH_DIR=build/cloud-hypervisor/$(ARCH)
+
+# Release assets and their sha256, per ARCH
+CH_ASSET_x86_64=cloud-hypervisor-static
+CH_SHA256_x86_64=4f4f98a3d661a40f3e5272627cc895a1b2e525f2f6bedf5f895f9cd21ba5c65b
+CH_REMOTE_ASSET_x86_64=ch-remote-static
+CH_REMOTE_SHA256_x86_64=acd5be240d5c73373effbe818908fc03e313ec8486237904bff11d93b71b1c83
+CH_FIRMWARE_ASSET_x86_64=CLOUDHV.fd
+CH_FIRMWARE_SHA256_x86_64=dc2fc8f0e43b96712d9fccc52a3a590769606412b3e1bc911d217addd3bef624
+
+ifneq ($(CH_ASSET_$(ARCH)),)
+	CH_PINNED=$(CH_DIR)/$(CH_VERSION)/$(CH_ASSET_$(ARCH))
+	CH_REMOTE_PINNED=$(CH_DIR)/$(CH_VERSION)/$(CH_REMOTE_ASSET_$(ARCH))
+	CH_FIRMWARE_PINNED=$(CH_DIR)/edk2-$(CH_FIRMWARE_VERSION)/$(CH_FIRMWARE_ASSET_$(ARCH))
+endif
+
+CH?=$(CH_PINNED)
+CH_REMOTE?=$(CH_REMOTE_PINNED)
+CH_FIRMWARE?=$(CH_FIRMWARE_PINNED)
+# Only the pinned files in use are downloaded.
+CH_DOWNLOADS=$(filter $(CH_PINNED) $(CH_REMOTE_PINNED) $(CH_FIRMWARE_PINNED),$(CH) $(CH_REMOTE) $(CH_FIRMWARE))
+
+CH_SMP?=4
+CH_MEM?=2048
+CH_API_SOCK?=$(BUILD)/ch.sock
+CH_LOG?=$(BUILD)/ch.log
+CH_TAP?=redox0
+CH_MAC?=52:54:00:12:34:56
+# Not in $(BUILD): SELinux limits passt to $XDG_RUNTIME_DIR and /tmp.
+CH_PASST_SOCK?=$(or $(XDG_RUNTIME_DIR),/tmp)/redox-passt-$(ARCH)-$(CONFIG_NAME).sock
+CH_PASST_FLAGS?=
+CHFLAGS?=-v --log-file $(CH_LOG)
+
+CHFLAGS+=--cpus boot=$(CH_SMP)
+CHFLAGS+=--firmware $(CH_FIRMWARE)
+CHFLAGS+=--serial tty --console off
+CHFLAGS+=--api-socket path=$(CH_API_SOCK)
+CHFLAGS+= \
+	--disk path=$(DISK),image_type=raw,serial=NVME_SERIAL \
+	--disk path=$(EXTRA_DISK),image_type=raw,serial=NVME_EXTRA
+
+PASST_RUN=
+
+ifeq ($(net),tap)
+	# The Redox virtio-net driver only acknowledges VIRTIO_NET_F_MAC at the moment.
+	CHFLAGS+=--net tap=$(CH_TAP),mac=$(CH_MAC),offload_tso=off,offload_ufo=off,offload_csum=off
+else ifneq ($(net),no)
+	CHFLAGS+=--net vhost_user=true,socket=$(CH_PASST_SOCK),mac=$(CH_MAC)
+	PASST_RUN=scripts/passt-run.sh "$(CH_PASST_SOCK)" $(CH_PASST_FLAGS) --
+endif
+
+ch_tap_found=$(shell ip link show "$(CH_TAP)" >/dev/null 2>&1 && echo yes)
+
+# vhost-user backends (virtiofsd, passt) need shared guest RAM.
+ifneq ($(strip $(share))$(PASST_RUN),)
+	CHFLAGS+=--memory size=$(CH_MEM)M,shared=on
+else
+	CHFLAGS+=--memory size=$(CH_MEM)M
+endif
+
+ifneq ($(strip $(share)),)
+	CHFLAGS+=$(foreach i,$(share_idx),--fs tag=$(call vfs_tag,$(i)),socket=$(call vfs_sock,$(i)))
+endif
+
+# $(1): CH, CH_REMOTE or CH_FIRMWARE. When it is set to something other than
+# the pinned download, it must be an existing file or a command in PATH.
+ch_check_set=$(if $(filter-out $($(1)_PINNED),$($(1))),$(if $(or $(wildcard $($(1))),$(shell command -v $($(1)))),,$(error $(1)=$($(1)) not found. Leave $(1) unset to use the pinned download)))
+
+.PHONY: ch ch-check ch-deps ch-fetch ch-shutdown
+
+ch-check:
+	$(if $(filter x86_64,$(ARCH)),,$(error Cloud Hypervisor: only ARCH=x86_64 is supported))
+	$(if $(filter $(HOST_ARCH),$(ARCH)),,$(error Cloud Hypervisor: ARCH=$(ARCH) cannot run on this $(HOST_ARCH) host))
+	$(call ch_check_set,CH)
+	$(call ch_check_set,CH_REMOTE)
+	$(call ch_check_set,CH_FIRMWARE)
+	$(if $(filter tap,$(net)),$(if $(ch_tap_found),,$(error no tap device $(CH_TAP). Create it with scripts/ch-tap-setup.sh or leave out net=tap to use passt)))
+
+ch-deps: $(DISK) $(EXTRA_DISK) $(CH_DOWNLOADS)
+
+ch-fetch: ch-check $(CH_DOWNLOADS)
+
+ch: ch-check ch-deps
+ifneq ($(wildcard $(MOUNT_DIR)),)
+	@echo "Disk is mounted. Unmounting the disk..."
+	$(MAKE) unmount
+endif
+	@if $(CH_REMOTE) --api-socket "$(CH_API_SOCK)" ping >/dev/null 2>&1; then \
+		echo "ch: a VM is already running on $(CH_API_SOCK); stop it with make ch-shutdown" >&2; \
+		exit 1; \
+	fi
+# A leftover socket file makes Cloud Hypervisor fail with "Address in use".
+	rm -f "$(CH_API_SOCK)"
+	$(VIRTIOFS_RUN) $(PASST_RUN) $(CH) $(CHFLAGS)
+
+ch-shutdown: $(filter $(CH_REMOTE_PINNED),$(CH_REMOTE))
+	$(call ch_check_set,CH_REMOTE)
+# shutdown alone would leave Cloud Hypervisor running.
+	$(CH_REMOTE) --api-socket "$(CH_API_SOCK)" shutdown-vmm
+
+# Downloads $(1) to $@ if its sha256 is $(2), and sets mode $(3) if given.
+# It goes through $@.partial, so $@ only ever holds a checked download.
+define ch_download
+	mkdir -p "$(@D)"
+	curl -fL --retry 3 --retry-delay 1 -o "$@.partial" "$(1)"
+	echo "$(2)  $@.partial" | sha256sum --check --quiet - \
+		|| { rm -f "$@.partial"; echo "ch: $(1) does not match the pinned sha256 $(2)" >&2; exit 1; }
+	$(if $(3),chmod $(3) "$@.partial")
+	mv "$@.partial" "$@"
+endef
+
+ifneq ($(CH_PINNED),)
+$(CH_PINNED):
+	$(call ch_download,$(CH_URL)/$(@F),$(CH_SHA256_$(ARCH)),+x)
+
+$(CH_REMOTE_PINNED):
+	$(call ch_download,$(CH_URL)/$(@F),$(CH_REMOTE_SHA256_$(ARCH)),+x)
+
+$(CH_FIRMWARE_PINNED):
+	$(call ch_download,$(CH_FIRMWARE_URL)/$(@F),$(CH_FIRMWARE_SHA256_$(ARCH)))
+endif

mk/qemu.mk

@@ -189,6 +189,20 @@ else
 	QEMUFLAGS+=-machine $(QEMU_MACHINE)
 endif
 
+# virtio-fs shares (share=...): the list is parsed in mk/virtiofs.mk.
+ifneq ($(strip $(share)),)
+	# vhost-user needs guest RAM to be shared with the virtiofsd processes, and
+	# the NUMA memdev must be exactly as large as -m. One backend serves all
+	# shares.
+	ifeq ($(UNAME),Linux)
+		QEMUFLAGS+=-object memory-backend-memfd,id=mem,size=$(QEMU_MEM)M,share=on
+	else
+		QEMUFLAGS+=-object memory-backend-file,id=mem,size=$(QEMU_MEM)M,mem-path=/dev/shm,share=on
+	endif
+	QEMUFLAGS+=-numa node,memdev=mem
+	QEMUFLAGS+=$(foreach i,$(share_idx),-chardev socket,id=vfs$(i),path=$(call vfs_sock,$(i)) -device vhost-user-fs-pci,queue-size=1024,chardev=vfs$(i),tag=$(call vfs_tag,$(i)))
+endif
+
 ifeq ($(audio),no)
 	# No audio
 else ifeq ($(audio),ac97)
@@ -383,9 +397,9 @@ $(BUILD)/qemu_uboot.rom:
 
 qemu: qemu-deps
 ifeq ($(wildcard $(MOUNT_DIR)),)
-	$(QEMU) $(QEMUFLAGS)
+	$(VIRTIOFS_RUN) $(QEMU) $(QEMUFLAGS)
 else
 	@echo "\033[1;38;5;196mDisk is mounted. Unmounting the disk...\033[0m";
 	$(MAKE) unmount
-	$(QEMU) $(QEMUFLAGS)
+	$(VIRTIOFS_RUN) $(QEMU) $(QEMUFLAGS)
 endif

mk/virtiofs.mk

@@ -0,0 +1,44 @@
+# Share host directories with the guest through virtio-fs (QEMU and Cloud Hypervisor).
+#   make qemu share=/path/to/dir                     # one share, tag is "host" by default
+#   make qemu share="tag=/path/to/dir"               # one share, tag is specified as "tag"
+#   make qemu share=/path/a share_tag=tag            # one share, tag is specified as "tag"
+#   make qemu share="tag_1=/path/a tag_2=/path/b"    # several shares: tag=dir ...
+#   make qemu share=redox                            # this build tree, tag "redox"
+#   make qemu share="redox=/other/path"              # ordinary share, tag "redox"
+#   make qemu share=/path/to/dir:ro                  # read-only, also tag=dir:ro and redox:ro
+#   make ch share=...                                # the same, on Cloud Hypervisor
+#
+# Each share gets its own host-side virtiofsd daemon (started and stopped by
+# scripts/virtiofs-run.sh), a vhost-user-fs device, and a virtio-fsd scheme
+# process on Redox. In the guest, a share appears at /scheme/virtio-fsd.<tag>.
+# The emulator flags for each share are added in mk/qemu.mk and mk/ch.mk.
+# Shared directories must exist. The guest cannot change anything in a :ro share.
+#
+# WARNING: share=redox exposes the whole build tree to the guest, including
+# the harddrive.img Redox is booted from, .git and .config. Writing to them
+# from Redox can corrupt the build system. share=redox:ro avoids that.
+
+share?=
+share_tag?=host
+share_sockdir?=$(BUILD)
+VIRTIOFS_RUN=
+
+ifneq ($(strip $(share)),)
+	share_norm:=$(foreach s,$(share),$(if $(filter redox redox:ro,$(s)),redox=$(ROOT)$(if $(filter %:ro,$(s)),:ro),$(s)))
+	ifeq ($(words $(share_norm)),1)
+		share_list:=$(if $(findstring =,$(share_norm)),$(share_norm),$(share_tag)=$(share_norm))
+	else
+		share_list:=$(share_norm)
+		share_bare:=$(foreach s,$(share_list),$(if $(findstring =,$(s)),,$(s)))
+		ifneq ($(strip $(share_bare)),)
+			# Keep the next line free of leading tabs: make would read it as a recipe.
+$(error share: every entry must be tag=dir when sharing several directories (bad: $(share_bare)); directories containing spaces are not supported)
+		endif
+	endif
+	share_idx:=$(shell seq 1 $(words $(share_list)))
+	vfs_entry=$(word $(1),$(share_list))
+	vfs_tag=$(firstword $(subst =, ,$(call vfs_entry,$(1))))
+	vfs_sock=$(share_sockdir)/virtiofsd-$(1).sock
+
+	VIRTIOFS_RUN=scripts/virtiofs-run.sh $(foreach i,$(share_idx),--share "$(call vfs_sock,$(i))" "$(call vfs_entry,$(i))") --
+endif

podman_bootstrap.sh

@@ -472,6 +472,116 @@ solus()
     fi
 }
 
+###############################################################################
+# virtiofsd is needed on the host by `make qemu share=<dir>` to share
+# directories with Redox (scripts/virtiofs-run.sh only looks for it).
+###############################################################################
+virtiofsd_find()
+{
+    local c
+    for c in "${VIRTIOFSD:-}" virtiofsd /usr/libexec/virtiofsd /usr/lib/qemu/virtiofsd \
+        "${XDG_CACHE_HOME:-$HOME/.cache}/virtiofsd-redox/virtiofsd"; do
+        [ -n "$c" ] || continue
+        if [ -f "$c" ] && [ -x "$c" ]; then
+            echo "$c"
+            return 0
+        fi
+        if command -v "$c" >/dev/null 2>&1; then
+            command -v "$c"
+            return 0
+        fi
+    done
+    return 1
+}
+
+###############################################################################
+# Download a static x86_64 virtiofsd build from the upstream CI into
+# ~/.cache/virtiofsd-redox, after asking for confirmation.
+# Override the source with VIRTIOFSD_URL.
+#
+# TODO: this is the CI build of upstream's main branch, so it is neither
+# pinned nor checked: virtiofsd releases do not ship binaries or checksums
+# yet. Once they do, move this download into mk/virtiofs.mk, pinned to a
+# release and checked against its sha256 like Cloud Hypervisor in mk/ch.mk,
+# and pass it to scripts/virtiofs-run.sh through VIRTIOFSD.
+###############################################################################
+virtiofsd_download()
+{
+    local url cache dest tmp answer
+    url="${VIRTIOFSD_URL:-https://gitlab.com/virtio-fs/virtiofsd/-/jobs/artifacts/main/raw/target/x86_64-unknown-linux-musl/release/virtiofsd?job=publish}"
+    cache="${XDG_CACHE_HOME:-$HOME/.cache}/virtiofsd-redox"
+    dest="$cache/virtiofsd"
+
+    if [ "$(uname -m)" != "x86_64" ]; then
+        echo "No prebuilt virtiofsd is available for $(uname -m)."
+        return 1
+    fi
+    echo "A static virtiofsd build can be downloaded from"
+    echo "  gitlab.com/virtio-fs/virtiofsd (CI artifact of the main branch)"
+    echo "to $dest"
+    printf "Download it now? (y/N): "
+    read answer || answer=""
+    if ! echo "$answer" | grep -iq "^y"; then
+        return 1
+    fi
+
+    mkdir -p "$cache"
+    tmp="$(mktemp "$cache/virtiofsd.XXXXXX")"
+    if command -v curl >/dev/null 2>&1; then
+        curl -fL --retry 3 --retry-delay 1 -o "$tmp" "$url" || { rm -f "$tmp"; return 1; }
+    elif command -v wget >/dev/null 2>&1; then
+        wget -O "$tmp" "$url" || { rm -f "$tmp"; return 1; }
+    else
+        echo "Need curl or wget to download virtiofsd."
+        rm -f "$tmp"
+        return 1
+    fi
+    if [ "$(head -c 4 "$tmp")" != "$(printf '\177ELF')" ]; then
+        echo "The download is not an ELF binary (see $url)."
+        rm -f "$tmp"
+        return 1
+    fi
+    chmod +x "$tmp"
+    mv -f "$tmp" "$dest"
+    echo "virtiofsd installed at $dest"
+}
+
+###############################################################################
+# This function makes sure virtiofsd is available: it looks for an existing
+# one, then tries the distribution package, then offers a download.
+# It never fails the bootstrap, virtiofsd is only needed for `share=`.
+# @params:	$1 the package manager to use on Debian-based Linux
+###############################################################################
+virtiofsd_setup()
+{
+    local found
+    echo "Checking for virtiofsd (used by 'make qemu share=<dir>')..."
+    if found="$(virtiofsd_find)"; then
+        echo "virtiofsd found at $found"
+        return 0
+    fi
+    echo "virtiofsd not found."
+
+    if command -v pacman >/dev/null 2>&1; then
+        sudo pacman -S --needed virtiofsd || true
+    elif command -v dnf >/dev/null 2>&1; then
+        sudo dnf install virtiofsd || true
+    elif command -v apt-get >/dev/null 2>&1 && apt-cache show virtiofsd >/dev/null 2>&1; then
+        sudo "$1" install virtiofsd || true
+    fi
+
+    if found="$(virtiofsd_find)"; then
+        echo "virtiofsd found at $found"
+        return 0
+    fi
+    if virtiofsd_download; then
+        return 0
+    fi
+    echo "Continuing without virtiofsd. 'make qemu share=<dir>' will not work until"
+    echo "it is installed (or set VIRTIOFSD=/path/to/virtiofsd), re-run this script"
+    echo "with -d to retry."
+}
+
 ######################################################################
 # This function outlines the different options available for bootstrap
 ######################################################################
@@ -659,6 +769,11 @@ else
     fi
 fi
 
+# Directory sharing with `make qemu share=<dir>` needs virtiofsd and a Linux host
+if [ "$emulator" == "qemu" ] && [ "$(uname -s)" == "Linux" ]; then
+    virtiofsd_setup "$defpackman"
+fi
+
 if [ "$dependenciesonly" = false ]; then
     boot
 fi

recipes/archives/bzip2/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Compression library and tools, bzip2/.bz2 format"
+
 [source]
 tar = "https://sourceware.org/pub/bzip2/bzip2-1.0.8.tar.gz"
 blake3 = "97af3f520629c65fe41292f77e6ca798fe594d7987bfb2aebe7c6fcdc7ab5ed2"

recipes/archives/libzip/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Compression library, .zip format, based on zlib"
+
 [source]
 tar = "https://libzip.org/download/libzip-1.11.4.tar.gz"
 blake3 = "844cf66c68f2dcf182f6626d5b72d55b75a100c0a93b3e6a45b447669ecf7088"

recipes/archives/lz4/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Compression library and tools, lz4 format"
+
 [source]
 tar = "https://github.com/lz4/lz4/releases/download/v1.10.0/lz4-1.10.0.tar.gz"
 blake3 = "3e69fd475e7852e17594985528b5232afeba7d3d56cfebe2e89071768b2ab36a"

recipes/archives/xz/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Compression library and tools, xz and .lzma format"
+
 [source]
 tar = "https://github.com/tukaani-project/xz/releases/download/v5.2.13/xz-5.2.13.tar.gz"
 blake3 = "edc6350542e8cb7188a878135e5b9bd592d687e5b47451ca1c89d51cc4bc6b53"

recipes/archives/zstd/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Compression library and tools, zstd/.zst format"
+
 [source]
 tar = "https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-1.5.7.tar.gz"
 blake3 = "730dca31244abd219e995f03a55d95b2cfb4b3e16cda055a79fa6f30a4f0e1db"

recipes/artwork/pop-wallpapers/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Wallpapers from Pop!_OS Linux"
+
 [source]
 git = "https://github.com/pop-os/wallpapers"
 shallow_clone = true

recipes/artwork/ubuntu-wallpapers/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Wallpapers from Ubuntu Linux"
+
 [source]
 tar = "https://launchpad.net/ubuntu/+archive/primary/+sourcefiles/ubuntu-wallpapers/23.10.4/ubuntu-wallpapers_23.10.4.orig.tar.gz"
 blake3 = "1e479d0aa48fe3f2961a2dac28c3ed397a29616cf6e7d73f5ceb6fabfd6449e1"

recipes/core/base/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Essential system components and drivers for Redox"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/base.git"
 

recipes/core/binutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Utilities for processing, manipulating, and inspecting binary files"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/binutils.git"
 

recipes/core/bootloader/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Redox OS bootloader"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/bootloader.git"
 

recipes/core/contain/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Containers and chroots for Redox"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/contain.git"
 

recipes/core/coreutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Core UNIX shell utilities"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/coreutils.git"
 

recipes/core/dash/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Standard POSIX shell, compatible with sh"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/dash.git"
 branch = "redox"

recipes/core/extrautils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Basic, but not essential for system function, UNIX shell utilities"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/extrautils.git"
 

recipes/core/findutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "UNIX find tool"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/findutils.git"
 

recipes/core/installer/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Builds a bootable Redox image"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/installer.git"
 

recipes/core/ion/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Official shell of the Redox project"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/ion.git"
 

recipes/core/kernel/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "The Redox microkernel"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/kernel.git"
 

recipes/core/netdb/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Default data files required for networking"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/netdb.git"
 

recipes/core/netutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Basic command-line networking utilities"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/netutils.git"
 

recipes/core/pkgar/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Package format utilities for Redox"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/pkgar.git"
 

recipes/core/pkgutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Standard package manager for Redox"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/pkgutils.git"
 

recipes/core/profiled/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Daemon used for profiling kernel (requires profiling-kernel recipe)"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/profiled.git"
 

recipes/core/profiling-kernel/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Kernel with profiling code enabled"
+
 [source]
 same_as = "../kernel"
 

recipes/core/redoxfs/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Official filesystem of the Redox project"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/redoxfs.git"
 

recipes/core/relibc/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Redox POSIX/C Standard Library"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/relibc.git"
 

recipes/core/strace/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Command-line utility for debugging the system"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/strace-redox.git"
 

recipes/core/userutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Command-line UNIX tools for managing users and groups"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/userutils.git"
 

recipes/core/uutils/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "General, useful command-line UNIX shell utilities (GNU Coreutils reimplemented in Rust)"
+
 # TODO Fix locale init bug caused by OnceLock combined with thread_local
 # TODO 0.12.0 requires rustix symlink_at
 [source]

recipes/cosmic/cosmic-edit/recipe.toml

@@ -24,6 +24,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical text editor from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-files/recipe.toml

@@ -24,6 +24,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical file manager from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-monitor/recipe.toml

@@ -23,6 +23,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical system monitor from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-reader/recipe.toml

@@ -38,6 +38,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical PDF reader from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-settings/recipe.toml

@@ -23,6 +23,7 @@ cp -rv "${COOKBOOK_SOURCE}/resources/icons/" "${COOKBOOK_STAGE}/usr/share/icons/
 """
 
 [package]
+description = "Graphical system settings from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-store/recipe.toml

@@ -24,6 +24,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical app store from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-term/recipe.toml

@@ -20,6 +20,7 @@ cp -rv "${COOKBOOK_SOURCE}/res/icons/hicolor/" "${COOKBOOK_STAGE}/usr/share/icon
 """
 
 [package]
+description = "Graphical terminal emulator from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/cosmic/cosmic-text/recipe.toml

@@ -15,6 +15,7 @@ COOKBOOK_CARGO_PATH=examples/editor cookbook_cargo_build
 """
 
 [package]
+description = "Demo of GUI text editing widget library from COSMIC desktop"
 dependencies = [
     "libxkbcommon",
 ]

recipes/data/ca-certificates/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "TLS certificate authorities, from the Mozilla CA Certificate Program"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/ca-certificates.git"
 

recipes/data/generaluser-gs/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "MIDI soundfont"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/generaluser-gs.git"
 

recipes/data/shared-mime-info/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "FreeDesktop common MIME database"
+
 # This does not build update-mime-database to avoid bringing in C code to Redox
 [source]
 tar = "https://gitlab.freedesktop.org/xdg/shared-mime-info/-/archive/2.4/shared-mime-info-2.4.tar.gz"

recipes/data/terminfo/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Tabset and terminfo databases"
+
 [source]
 git = "https://github.com/sajattack/terminfo"
 branch = "master"

recipes/demos/cairo-demo/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Demo of Cairo GUI library"
+
 # source is part of cookbook
 
 [build]

recipes/demos/cmatrix/recipe.toml

@@ -25,6 +25,7 @@ sed -i -e 's|#define USE_TIOCSTI 1|/* #undef USE_TIOCSTI */|g' config.h
 """
 
 [package]
+description = "Terminal based character raining effect from the Matrix movies"
 dependencies = [
     "terminfo"
 ]

recipes/demos/cpal/recipe.toml

@@ -1,3 +1,7 @@
+# TODO: When more CPAL examples are added, description should be changed
+[package]
+description = "Command line beep tool (demo from CPAL sound library)"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/cpal.git"
 branch = "redox"

recipes/demos/dynamic-example/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Example of a dynamic library for Redox"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/dynamic-example.git"
 shallow_clone = true

recipes/demos/exampled/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Redox device driver daemon example"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/exampled.git"
 

recipes/demos/gears/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Mesa3D \"gears\" OpenGL demo ported to Orbital windowing"
+
 [build]
 dependencies=[
     "liborbital",

recipes/demos/glutin/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Demo of Glutin OpenGL-initialization library"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/glutin.git"
 branch = "redox-0.30"

recipes/demos/iced/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Examples from Iced GUI library"
+
 [source]
 git = "https://github.com/pop-os/iced"
 rev = "300fa97" 

recipes/demos/orbclient/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Orbital client library example"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/orbclient.git"
 

recipes/demos/osdemo/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Mesa3D offscreen rendering (OSMesa) demo using Orbital windowing"
+
 [build]
 template = "custom"
 dependencies = [

recipes/demos/pixelcannon/recipe.toml

@@ -15,6 +15,7 @@ cp -v "${COOKBOOK_SOURCE}/manifest" "${COOKBOOK_STAGE}/usr/share/ui/apps/pixelca
 """
 
 [package]
+description = "3D laughing face meme navigation demo"
 dependencies = [
     "orbital",
 ]

recipes/demos/sdl2-gears/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Mesa3D \"gears\" OpenGL demo ported to SDL2 windowing"
+
 [build]
 template = "custom"
 dependencies = [

recipes/demos/softbuffer/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Examples from softbuffer GUI framebuffer library"
+
 # NOTE: Switch to upstream once winit pump events have been upstreamed
 [source]
 git = "https://github.com/willnode/softbuffer.git"

recipes/demos/winit/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Examples from winit GUI library"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/winit"
 branch = "redox-0.31.0-beta"

recipes/dev/autoconf/recipe.toml

@@ -6,4 +6,5 @@ blake3 = "da1cc8af8551c343de9f42af0ae53fd7dff3623487157623892b6cd7e3bb5692"
 template = "configure"
 
 [package]
+description = "Tools for self-configuring software source code (creates \"configure\" script)"
 dependencies = ["perl5"]

recipes/dev/automake/recipe.toml

@@ -6,4 +6,5 @@ blake3 = "f42cfc333aaaa11f2bcb05b5b0273b8706c820c22f9ba4367f7eb920551695cd"
 template = "configure"
 
 [package]
+description = "Tools for high-level build scripting atop GNU Make (creates \"Makefile.in\")"
 dependencies = ["perl5"]

recipes/dev/binutils-gdb/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "GNU Binutils version of GDB debugger"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/binutils-gdb"
 branch = "redox-2.43.1"

recipes/dev/clang21/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "LLVM C/C++ frontend/compiler"
+
 [source]
 same_as = "../llvm21"
 

recipes/dev/cmake/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Widely-used cross-platform build system"
+
 [source]
 tar = "https://github.com/Kitware/CMake/releases/download/v4.3.2/cmake-4.3.2.tar.gz"
 blake3 = "cbd0121189df1502f61e8f12f044b4a901b1ea16c74c016b85714e4661b8537f"

recipes/dev/composer/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "A dependency manager for PHP"
+
 #TODO must be run using `php $(which composer)`
 [build]
 template = "custom"

recipes/dev/fontconfig/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Library and tools to configure, enumerate, and substitute fonts"
+
 [source]
 tar = "https://www.freedesktop.org/software/fontconfig/release/fontconfig-2.16.0.tar.xz"
 blake3 = "5c95d48f5b9150f4a06d8acac12c25edaac956007df95a3bf527df02a5908f0e"

recipes/dev/gcc13/recipe.toml

@@ -100,6 +100,7 @@ fi
 """
 
 [package]
+description = "GNU Compiler Collection"
 dependencies = [
     "gnu-binutils"
 ]

recipes/dev/gdbserver/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "GDB server for remote debugging"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/gdbserver.git"
 

recipes/dev/gdk-pixbuf/recipe.toml

@@ -23,6 +23,7 @@ mesonflags = [
 ]
 
 [package]
+description = "Image loading library from GNOME project"
 dependencies = [
     "shared-mime-info",
 ]

recipes/dev/git/recipe.toml

@@ -44,6 +44,7 @@ cp "${COOKBOOK_RECIPE}/gitconfig" "${COOKBOOK_STAGE}/etc/"
 """
 
 [package]
+description = "Distributed version control system"
 dependencies = [
     "ca-certificates",
 ]

recipes/dev/gitoxide/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Rust reimplementation of Git"
+
 [source]
 git = "https://github.com/Byron/gitoxide.git"
 rev = "v0.54.0"

recipes/dev/gnu-make/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "GNU version of Make tool"
+
 #TODO slower jobserver due to lack of named pipes
 [source]
 tar = "http://ftp.gnu.org/gnu/make/make-4.4.tar.gz"

recipes/dev/hello-world-examples/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "\"Hello world\" examples in over 1000 languages"
+
 [source]
 git = "https://github.com/leachim6/hello-world"
 shallow_clone = true

recipes/dev/jq/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Command-line JSON processor"
+
 #TODO undefined reference
 [source]
 tar = "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-1.8.1.tar.gz"

recipes/dev/lci/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Interpreter for LOLCODE programming language"
+
 [source]
 git = "https://github.com/jD91mZM2/rust-lci"
 

recipes/dev/libtool/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Tools for working with shared libraries"
+
 #TODO can build, not tested
 [source]
 git = "https://gitlab.redox-os.org/redox-os/libtool"

recipes/dev/lld21/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "The LLVM linker"
+
 [source]
 same_as = "../llvm21"
 

recipes/dev/llvm-rt21/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "LLVM 21.x libraries and tools additional support libraries used by Clang"
+
 [source]
 same_as = "../llvm21"
 

recipes/dev/llvm18/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "LLVM 18.x libraries and tools"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/llvm-project.git"
 upstream = "https://github.com/rust-lang/llvm-project.git"

recipes/dev/llvm21/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Libraries and tools for LLVM generic compiler backend, version 21"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/llvm-project.git"
 upstream = "https://github.com/rust-lang/llvm-project.git"

recipes/dev/lua54/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Lua programming language, PUC-Rio distribution, version 5.4"
+
 [source]
 tar = "https://lua.org/ftp/lua-5.4.7.tar.gz"
 blake3 = "e51c2f347e3185479d5ff95cae8ac77511db486853269443c56bedaa0a6ae629"

recipes/dev/luajit/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "JIT version of Lua programming language, version 5.1 plus extensions"
+
 [source]
 git = "https://luajit.org/git/luajit.git"
 rev = "a4f56a459a588ae768801074b46ba0adcfb49eb1"

recipes/dev/luarocks/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Package manager for Lua programming language"
+
 [source]
 git = "https://github.com/luarocks/luarocks.git"
 shallow_clone = true

recipes/dev/nasm/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "x86 assembler"
+
 [source]
 #TODO: nasm.us is down: tar = "https://www.nasm.us/pub/nasm/releasebuilds/2.14.02/nasm-2.14.02.tar.gz"
 tar = "https://gstreamer.freedesktop.org/src/mirror/nasm-2.14.02.tar.xz"

recipes/dev/patch/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Tool to apply a diff file to an original"
+
 [source]
 tar = "https://ftp.gnu.org/gnu/patch/patch-2.7.6.tar.xz"
 blake3 = "d46d14c12aa4ea51e356bf92091c368fd871e1d770b94bc29027886737aecd5f"

recipes/dev/pciids/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Data file mapping that maps PCI IDs to human-readable names"
+
 [source]
 git = "https://github.com/pciutils/pciids.git"
 

recipes/dev/php84/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Web-centric programming language"
+
 [source]
 tar = "https://www.php.net/distributions/php-8.4.17.tar.xz"
 blake3 = "a8478dddd948d4b26e51c5727ac0895440da76e8ad9be947098a4284ca0b7f2a"

recipes/dev/pkg-config/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Tool for querying library paths and configuration information"
+
 [source]
 tar = "https://pkg-config.freedesktop.org/releases/pkg-config-0.29.2.tar.gz"
 blake3 = "713372b09a1fafeec130dc9bf812a3880f2a90496af5d2194e508d91ccf667d0"

recipes/dev/python312/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Object-oriented interpreted programming language, version 3.12.x"
+
 [source]
 tar = "https://www.python.org/ftp/python/3.12.12/Python-3.12.12.tar.xz"
 blake3 = "29636fdae3e0ee8d0fe585e528c9376fe43876f5f3f0f7892140567946fd907b"

recipes/dev/redoxer/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Wrapper and command-line tool to quickly test and run Rust, C, and C++ applications and libraries in a minimal Redox virtual machine"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/redoxer"
 branch = "master"

recipes/dev/rust/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Rust compiler and tooling"
+
 [source]
 git = "https://gitlab.redox-os.org/redox-os/rust.git"
 branch = "redox-2026-05-24"

recipes/dev/rustpython/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Python interpreter written in Rust"
+
 [source]
 git = "https://github.com/RustPython/RustPython"
 # newer rev requires 'bits/libc-header-start.h' for bindgen

recipes/dev/wasi-libc/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "C Standard Library implementation for WebAssembly/WASI"
+
 # NOTE: This is only used to compile into wasi
 [source]
 git = "https://github.com/WebAssembly/wasi-libc"

recipes/dri/drm-info/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Tool to dump information about Linux Direct Rendering Manager drivers"
+
 [source]
 tar = "https://gitlab.freedesktop.org/emersion/drm_info/-/archive/v2.9.0/drm_info-v2.9.0.tar.gz"
 blake3 = "48ff592b206a85c1d946abfe2f8a4e7ef40f9f1ee7d3d5ee454a33390f86d8cb"

recipes/emulators/dosbox/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "MS-DOS emulator"
+
 [source]
 tar = "https://sourceforge.net/projects/dosbox/files/dosbox/0.74-3/dosbox-0.74-3.tar.gz/download"
 blake3 = "8bc50ffdba20579fb3080a0dca32cb939c8a3c19259aed026482c6ac069b0007"

recipes/emulators/flycast/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Sega Dreamcast, Naomi, Naomi 2, and Atomiswave emulator"
+
 [source]
 git = "https://github.com/flyinghead/flycast.git"
 rev = "v2.6"

recipes/emulators/libretro-super/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "libretro library and cores"
+
 [source]
 git = "https://github.com/jackpot51/libretro-super.git"
 shallow_clone = true

recipes/emulators/mednafen/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Multi-emulator for various vintage systems"
+
 [source]
 tar = "https://mednafen.github.io/releases/files/mednafen-1.29.0.tar.xz"
 blake3 = "c75c1044cdc9328b2349915a67972d6135c77eb53eb0d995788f22b7daacf79b"

recipes/emulators/mgba/recipe.toml

@@ -1,3 +1,6 @@
+[package]
+description = "Game Boy Advance emulator"
+
 [source]
 tar = "https://github.com/mgba-emu/mgba/archive/0.10.5.tar.gz"
 blake3 = "a1b9e797a5058f5264d276805aef5643b7ea460916e491a0098ba32d87f1519e"