From 4ac7e19397efc75b0d8b374ab28c3e4e21185306 Mon Sep 17 00:00:00 2001 From: Nexoniarz Date: Sun, 9 Aug 2026 17:25:07 +0200 Subject: [PATCH] Prepare for the move to Fedora tools/posix/setup-fedora.sh installs the toolchain and reports what it cannot: PowerShell has no Fedora package, and bootcheck is the test suite, so the script says how to get pwsh rather than failing quietly. It also checks /dev/kvm, since a Ryzen box can run the tests at native speed. docs/moving-to-linux.md is the actual procedure: copy the repo, restore the memory, install, build. The memory travels inside the repo and `memory-sync.sh import` puts it under the key this machine derives from its own path -- /home/nexoniarz/Documents/SchOS becomes -home-nexoniarz-Documents-SchOS, where D:\DEV\SchOS was D--DEV-SchOS. OVMF discovery no longer assumes QEMU's Windows layout. Fedora ships edk2-ovmf to /usr/share/edk2/ovmf/, Debian and Arch differ again, so the Makefile searches a list and names the packages when it finds nothing. Tested through the shell rather than $(wildcard): on Windows make is a native binary using Win32 file calls, while `command -v` returns an MSYS path like /c/Users/..., which $(wildcard) cannot see -- it returned nothing on a machine that had the firmware. Two things only that machine can test: `make ports` builds musl, toybox and mksh from source, which Windows cannot do at all; and the SchFS round-trip needs symlinks and hard links, so it has never actually run. --- Makefile | 25 +++++++- README.md | 4 +- docs/building.md | 10 +++ docs/moving-to-linux.md | 120 ++++++++++++++++++++++++++++++++++++ tools/posix/setup-fedora.sh | 94 ++++++++++++++++++++++++++++ 5 files changed, 249 insertions(+), 4 deletions(-) create mode 100644 docs/moving-to-linux.md create mode 100644 tools/posix/setup-fedora.sh diff --git a/Makefile b/Makefile index cd94090..f82b9e7 100644 --- a/Makefile +++ b/Makefile @@ -383,16 +383,35 @@ esp: $(BUILD)/esp/EFI/BOOT/BOOTX64.EFI # simply not be there. OVMF_CODE = $(BUILD)/OVMF_CODE.fd OVMF_VARS = $(BUILD)/OVMF_VARS.fd -QEMU_SHARE = $(dir $(shell command -v $(QEMU)))share +# OVMF, wherever this host keeps it. +# +# There is no common location: QEMU's own Windows build puts it beside the +# binary as edk2-x86_64-code.fd, Fedora ships edk2-ovmf into +# /usr/share/edk2/ovmf/OVMF_CODE.fd, Debian and Arch each differ again. Search +# rather than assume, and say something useful when nothing is found -- an +# unhelpful "cp: no such file" is a poor way to learn that a package is +# missing. +QEMU_SHARE = $(dir $(shell command -v $(QEMU) 2>/dev/null))share +OVMF_CODE_CANDIDATES = $(QEMU_SHARE)/edk2-x86_64-code.fd /usr/share/edk2/ovmf/OVMF_CODE.fd /usr/share/OVMF/OVMF_CODE.fd /usr/share/ovmf/x64/OVMF_CODE.fd /usr/share/qemu/edk2-x86_64-code.fd +OVMF_VARS_CANDIDATES = $(QEMU_SHARE)/edk2-i386-vars.fd /usr/share/edk2/ovmf/OVMF_VARS.fd /usr/share/OVMF/OVMF_VARS.fd /usr/share/ovmf/x64/OVMF_VARS.fd /usr/share/qemu/edk2-i386-vars.fd + +# Tested through the shell rather than with $(wildcard). On Windows, make is a +# native binary using Win32 file calls while `command -v` hands back an MSYS +# path like /c/Users/..., which $(wildcard) cannot see -- it silently returns +# nothing and the firmware looks missing on a machine that has it. +OVMF_CODE_SRC = $(shell for f in $(OVMF_CODE_CANDIDATES); do [ -f "$$f" ] && { echo "$$f"; break; }; done) +OVMF_VARS_SRC = $(shell for f in $(OVMF_VARS_CANDIDATES); do [ -f "$$f" ] && { echo "$$f"; break; }; done) $(OVMF_CODE): @mkdir -p $(BUILD) - cp "$(QEMU_SHARE)/edk2-x86_64-code.fd" $@ + @test -n "$(OVMF_CODE_SRC)" || { echo "no OVMF firmware found. Install it:"; echo " Fedora sudo dnf install edk2-ovmf"; echo " Debian sudo apt install ovmf"; echo " Arch sudo pacman -S edk2-ovmf"; exit 1; } + cp "$(OVMF_CODE_SRC)" $@ chmod u+w $@ $(OVMF_VARS): @mkdir -p $(BUILD) - cp "$(QEMU_SHARE)/edk2-i386-vars.fd" $@ + @test -n "$(OVMF_VARS_SRC)" || { echo "no OVMF varstore found -- install the OVMF package (see above)"; exit 1; } + cp "$(OVMF_VARS_SRC)" $@ chmod u+w $@ qemu-uefi: esp $(BUILD)/schfs.img $(OVMF_CODE) $(OVMF_VARS) diff --git a/README.md b/README.md index bbc9973..57a7761 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,9 @@ Builds on **Linux, macOS, FreeBSD/OpenBSD/NetBSD and Windows** (Git Bash). The toolchain is clang + lld everywhere — it is a cross-compiler by construction, so one LLVM install targets the bare-metal kernel, the 16-bit boot code and musl userland from any host. See **[docs/building.md](docs/building.md)** for -prerequisites per platform. +prerequisites per platform, and +**[docs/moving-to-linux.md](docs/moving-to-linux.md)** for moving a checkout +between machines. ## Testing diff --git a/docs/building.md b/docs/building.md index c1374ce..6558949 100644 --- a/docs/building.md +++ b/docs/building.md @@ -104,6 +104,16 @@ outstanding: `Join-Path $root 'build\x'` produces a *filename containing a backslash* on a Unix host. +## Fedora, in one command + +```sh +tools/posix/setup-fedora.sh --check # what is missing +tools/posix/setup-fedora.sh # install it +``` + +Moving an existing checkout to a Linux machine: see +[moving-to-linux.md](moving-to-linux.md). + ## Working on two machines Claude Code's project memory is kept in the repo and moved with: diff --git a/docs/moving-to-linux.md b/docs/moving-to-linux.md new file mode 100644 index 0000000..83ec12c --- /dev/null +++ b/docs/moving-to-linux.md @@ -0,0 +1,120 @@ + +# Moving the project to a Linux machine + +Written for the move to `/home/nexoniarz/Documents/SchOS` on Fedora 44. Nothing +here is Fedora-specific except the package names. + +## 1. Copy the repo + +Copy the whole directory, `.git` included. Everything that matters is committed +— 17 commits, no remote — and that includes the project memory, which lives in +`.claude/memory/` precisely so it survives this. + +```sh +# whatever transport suits: a USB stick, rsync, scp +rsync -a /path/to/SchOS/ /home/nexoniarz/Documents/SchOS/ +cd /home/nexoniarz/Documents/SchOS +git log --oneline | head -3 # should show the same commits +git status # should be clean +``` + +`build/` and `sysroot/` are ignored and do not need copying — `make` rebuilds +them. **One exception**: `sysroot/bin/` holds musl, toybox and mksh, which +cannot be built on Windows and so were staged there once. On Linux they *can* +be built, so let the build produce them (`make ports`) rather than carrying +stale binaries across. The staged copies predate the SchOS rename anyway — +`sysroot/bin/sh` still contains the symbol `__schunix_tp`. + +## 2. Restore the memory + +Claude Code keeps per-project memory under a key derived from the project's +absolute path, so it differs per machine: + +| | | +|---|---| +| `D:\DEV\SchOS` | `D--DEV-SchOS` | +| `/home/nexoniarz/Documents/SchOS` | `-home-nexoniarz-Documents-SchOS` | + +One command puts it where this machine looks: + +```sh +tools/posix/memory-sync.sh status # shows both sides, changes nothing +tools/posix/memory-sync.sh import # repo -> ~/.claude/projects//memory/ +``` + +That writes to +`/home/nexoniarz/.claude/projects/-home-nexoniarz-Documents-SchOS/memory/`. + +After a session that learned something, `export` and commit, so the knowledge +travels back: + +```sh +tools/posix/memory-sync.sh export && git add -A && git commit -m "memory: ..." +``` + +## 3. Install the toolchain + +```sh +tools/posix/setup-fedora.sh --check # report what is missing +tools/posix/setup-fedora.sh # install it +``` + +That covers clang, lld, llvm, make, gcc, perl, python3, qemu-system-x86, +edk2-ovmf, xorriso and mtools. See [building.md](building.md) for what each is +for and for the other supported hosts. + +**PowerShell is the one thing dnf cannot supply.** `tools/windows/bootcheck.ps1` +is the boot test suite, and `pwsh` runs it on Linux perfectly well — there is +simply no Fedora package. The script prints the two ways to get it. Nothing +else needs it: `make`, `make schfs-check` and `make qemu` all work without. + +## 4. Build and check + +```sh +make # kernel + root filesystem -> schos.img +make schfs-check # B-tree, object and image suites -- all host-native +make qemu # boot it +``` + +Two things will behave differently here, both improvements: + +- **`make ports` works.** musl, toybox and mksh build from source. On Windows + the build skips them and uses whatever is staged. +- **The SchFS round-trip test runs.** It needs symlinks and hard links, which + Git Bash cannot create, so on Windows it skips with a message. This is the + first machine that can actually exercise that path — worth running early, + since it is the one part of SchFS never yet tested. + +## 5. KVM + +A Ryzen 7000 has SVM, so QEMU can run at native speed instead of emulating: + +```sh +ls -l /dev/kvm # should exist +sudo usermod -aG kvm $(id -un) # if it exists but is not readable +``` + +Then add `-enable-kvm` to a QEMU command line. It is deliberately **not** the +default in the Makefile: the test suite's timings were established under TCG, +and changing the execution engine underneath them is a variable worth +introducing on purpose rather than by accident. + +## 6. UEFI + +`make qemu-uefi` boots the UEFI path under OVMF. The Makefile searches the +usual locations for the firmware and Fedora's `edk2-ovmf` +(`/usr/share/edk2/ovmf/OVMF_CODE.fd`) is among them. + +Note the open bug before spending time on it: under OVMF the kernel reports +`e820: only 8 MB usable`, because `e820_init` takes the usable run *containing +the kernel* and OVMF puts an ACPI NVS region at 0x800000, genuinely fragmenting +it. The loader's map is correct; the kernel's one-contiguous-run assumption is +BIOS-shaped. The fix is to free each usable region rather than one range, which +touches `kalloc`. + +## The hardware, for reference + +Fedora 44, Ryzen 5 7000-series, RTX 4050, 16 GB DDR5. Nothing in the build cares +about the GPU — QEMU runs headless for tests and uses its own emulated display +otherwise. The Nvidia driver matters only if you want a QEMU window, and the +`nouveau`/proprietary choice makes no difference to SchOS either way. diff --git a/tools/posix/setup-fedora.sh b/tools/posix/setup-fedora.sh new file mode 100644 index 0000000..8de54fa --- /dev/null +++ b/tools/posix/setup-fedora.sh @@ -0,0 +1,94 @@ +#!/bin/sh +# Install what SchOS needs to build and test, on Fedora. +# +# tools/posix/setup-fedora.sh install everything +# tools/posix/setup-fedora.sh --check report what is missing, install nothing +# +# Written for Fedora 44. Package names are stable enough that older and newer +# releases should work unchanged; the --check mode exists so a wrong guess +# reports itself instead of failing halfway through a dnf transaction. + +set -eu + +CHECK=0 +[ "${1:-}" = "--check" ] && CHECK=1 + +# Toolchain. clang and lld are the whole cross-compiler story -- see +# docs/building.md for why there is no cross-gcc here. +PKGS="clang lld llvm make gcc perl-interpreter python3 git" + +# Running and testing. +PKGS="$PKGS qemu-system-x86 edk2-ovmf xorriso" + +# mtools is for building a real FAT ESP image. Not needed yet -- the UEFI +# target serves a directory as FAT through QEMU -- but it is what `make iso` +# will want once the ISO carries an EFI entry. +PKGS="$PKGS mtools" + +# Ports are built from source on this host, which is the reason a Linux box +# matters: they cannot be built on Windows at all. +PKGS="$PKGS tar curl xz bzip2 diffutils findutils" + +missing="" +for p in $PKGS; do + rpm -q "$p" >/dev/null 2>&1 || missing="$missing $p" +done + +if [ -z "$missing" ]; then + echo "all packages present" +else + echo "missing:$missing" + if [ "$CHECK" -eq 0 ]; then + echo + echo "installing..." + sudo dnf install -y $missing + fi +fi + +# PowerShell is not in Fedora's repositories and is not an rpm you can name. +# +# It matters because tools/windows/bootcheck.ps1 is the test harness, and pwsh +# runs it on Linux perfectly well -- there is simply no dnf package. Microsoft +# publish a repo; the tarball is the lighter option and needs no root beyond +# the install path. +if command -v pwsh >/dev/null 2>&1; then + echo "pwsh: $(command -v pwsh)" +else + cat <<'EOF' + +pwsh is not installed. tools/windows/bootcheck.ps1 is the boot test suite and +needs it. Either: + + sudo dnf install -y https://packages.microsoft.com/config/rhel/9/packages-microsoft-prod.rpm + sudo dnf install -y powershell + +or take the tarball from https://github.com/PowerShell/PowerShell/releases and +put pwsh on PATH. Nothing else in the build depends on it -- `make`, +`make schfs-check` and `make qemu` all work without. +EOF +fi + +echo +echo "checks:" +for t in clang ld.lld llvm-objcopy make gcc perl python3 qemu-system-x86_64 xorriso; do + if command -v "$t" >/dev/null 2>&1; then + printf ' %-22s ok\n' "$t" + else + printf ' %-22s MISSING\n' "$t" + fi +done + +# KVM is the difference between a boot test that takes seconds and one that +# takes half a minute. It needs the module loaded and the user in the kvm +# group; a Ryzen box has it unless virtualisation is off in firmware. +echo +if [ -e /dev/kvm ]; then + if [ -r /dev/kvm ] && [ -w /dev/kvm ]; then + echo "kvm: available and usable -- add -enable-kvm to QEMU for much faster boots" + else + echo "kvm: present but not accessible. Fix with:" + echo " sudo usermod -aG kvm $(id -un) && newgrp kvm" + fi +else + echo "kvm: /dev/kvm missing -- check that SVM/virtualisation is enabled in firmware" +fi