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

<!-- SPDX-License-Identifier: GPL-2.0-or-later -->
# 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](../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.

```sh
# 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:

```sh
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:

```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 [../guides/building.md](../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

```sh
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:

```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.