docs: four directories, and a rule for when a thing leaves the roadmap
docs/ was ten files where a plan, a description, a guide and a bug report all
sat next to each other. It is now architecture/ (what SchOS is), plan/ (what it
will be), guides/ (how to work on it) and history/ (why it is like this), with
an index that states the one rule holding it together: when something is
finished it moves from plan/ to architecture/ and is rewritten as a description
of the thing rather than a record of building it.
A ticked checkbox says the work happened. It does not say what the work
*produced*, and six months later the checkbox is all that is left. The network
stack proved the point: finished, verified end to end, and for a month the only
description of it anywhere was a checkbox four levels of indentation deep.
So roadmap.md went from 534 lines to 181 -- nothing deleted, the done work
graduated. Seven subsystems that were finished and undescribed now have
descriptions: boot, kernel, syscalls, filesystem, networking, graphics, usb,
init. Every one ends with "What it does not do", which is the section that pays;
a document listing only strengths is marketing, and the reader who needs it most
is the one about to trip over a limitation nobody wrote down.
schfs.md still opened with "phases 1 through 3 1/2 are done, phase 4 is next"
long after all five had landed. It is a description now, with the phase record
and the hard-won bugs moved to history/.
Three corrections found on the way, all load-bearing:
* projects/schcom/README.md claimed SCM_RIGHTS was done. There is no
sendmsg/recvmsg in the kernel at all, and an entire GUI plan rested on it.
* The root README said "No TCP/IP" months after the stack landed.
* history/kernel.md sec.7 was marked "in progress" on a problem that process
groups solved.
Also adds plan/1.0.md, which draws a finish line so the open list stops being
infinite, and marks schwm/ and schde/ superseded: in Wayland the compositor is
the window manager, so that split dissolves rather than being abandoned.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
This commit is contained in:
Nexoniarz
parent
817d666068
commit
57aff40228
59 changed files with 3981 additions and 1124 deletions
|
|
@ -1,131 +0,0 @@
|
|||
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
||||
# 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
|
||||
```
|
||||
|
||||
### 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/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/<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 [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
|
||||
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.
|
||||
Loading…
Reference in a new issue