SchOS/docs/history/moving-to-linux.md

Moving the project to a Linux machine

This move happened. The tree lives on Fedora now, and the checkout is at /home/nexoniarz/Dokumenty/Projects/SchOS rather than the path written below.

It is kept in history/ rather than guides/ because most of it is a one-time procedure that has been performed — but three parts recur and are worth knowing before the next machine:

• what is and is not in the repo (§1), which decides what a git clone gives you versus an rsync
• the memory key is derived from the absolute path (§2), so it differs per machine and memory-sync.sh exists for exactly that
• the two things that behave differently on Linux (§4) — make ports works, and the SchFS round-trip test actually runs, because it needs symlinks and hard links that Git Bash cannot create

Nothing here is Fedora-specific except the package names. For building on any host, see ../guides/building.md.

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.

# whatever transport suits: a USB stick, rsync, scp
rsync -a /path/to/SchOS/ /home/nexoniarz/Dokumenty/Projects/SchOS/
cd /home/nexoniarz/Dokumenty/Projects/SchOS
git log --oneline | head -3     # should show the same commits
git status                      # should be clean

What is not in the repo

build/, sysroot/ and dist/ are all gitignored, so rsync -a of the working tree carries them but a git clone would not. Two are worth thinking about:

• dist/ holds the upstream tarballs — musl, toybox, mksh, the DOOM WADs, usb.ids. 61 MB of other people's release artefacts. Copy it to save the download, or let the build fetch them again; make ports calls curl and verifies each against a known SHA-256, so a re-download is safe either way. Without a network connection, copy it.
• sysroot/ is assembled by the build, so it does not need copying — and on this machine it should not be. Its bin/ holds musl, toybox and mksh, staged once because Windows cannot build them. Linux can, so let make ports produce them rather than carrying stale binaries across: the staged copies predate the rename, and sysroot/bin/sh still contains __schunix_tp.
• build/ is pure output. Delete it and forget it.

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/Dokumenty/Projects/SchOS	-home-nexoniarz-Dokumenty-Projects-SchOS

One command puts it where this machine looks:

tools/posix/memory-sync.sh status   # shows both sides, changes nothing
tools/posix/memory-sync.sh import   # repo -> ~/.claude/projects/<key>/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:

tools/posix/memory-sync.sh export && git add -A && git commit -m "memory: ..."

3. Install the toolchain

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 ../guides/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

make                    # kernel + root filesystem
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:

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.