---
name: schos-cross-platform-build
description: "The build and tools support Windows, Linux, macOS and BSD; clang everywhere, and the four host assumptions that used to break"
metadata: 
  node_type: memory
  type: project
  originSessionId: 9d8a2aef-bcf0-47a0-96c6-f706efab4a95
  modified: 2026-08-09T12:26:54.787Z
---

**Nexoniarz develops from both Windows and Linux and switches between them**, so
nothing in the build may assume a host. As of 2026-08-09 all four are supported:
Windows (Git Bash/MSYS), Linux, macOS, and the BSDs. See
[[schunix-build-environment]] for why WSL is not an option on the Windows box.

**One toolchain, not two.** clang is a cross-compiler by construction, so a
single LLVM install produces every target the tree needs — bare-metal ELF, the
16/32-bit code below 1 MB, and Linux/musl userland — from any host. The Makefile
picks clang+lld whenever both are on PATH; `USE_GNU=1` forces the GNU fallback.
The old GNU branch had rotted: it passed `--no-warn-rwx-segments`, which is a
**hard error on lld**, and lld is the default linker on FreeBSD and macOS. It
also wanted a brewed `x86_64-elf-gcc` before a Mac could build at all.

**Host tools use the host's own `cc`.** Only mingw needs naming explicitly, and
only because clang defaults to an MSVC target there while `tools/mkfs.c` needs
`<unistd.h>` and `<dirent.h>`.

**The four things that were actually host-specific**, all fixed — worth
recognising the pattern before adding a fifth:

1. `<sys/sysmacros.h>` is glibc/musl only. macOS and the BSDs have no such
   header and take `major()`/`minor()` from `<sys/types.h>`. Guarded on
   `__linux__` now.
2. `sha256sum -c -` exists on Linux and Git Bash only. macOS has `shasum -a
   256`, FreeBSD/NetBSD `sha256`, OpenBSD `cksum -a sha256`. `tools/sha256check.sh`
   tries all five and compares digests itself rather than trusting a `-c` flag,
   whose input format also differs.
3. `nproc` is coreutils — absent on macOS and BSD, where it is
   `sysctl -n hw.ncpu`.
4. **`Join-Path $root 'build\x'` produces a filename containing a backslash on
   a Unix host.** PowerShell 7 runs on Linux/macOS/BSD, so the .ps1 tools are
   usable there, but only with forward slashes throughout and QEMU found on
   PATH instead of a hardcoded scoop location.

**Do not blanket-replace backslashes in the .ps1 tools.** `bootcheck.ps1` sends
`printf 'caf\303\251'` to the guest to test UTF-8; rewriting those octal escapes
changes what the test asserts without failing it. The sweep is restricted to
known directory prefixes for exactly this reason.

**Ports do not build on Windows** — `make ports` skips with a message and the
tree relies on `sysroot/` being pre-staged. Building musl/toybox/mksh from
source needs a Linux host. That is a real reason to keep the Linux path working,
not a theoretical one.

**Unverified, and say so when it matters:** the Linux, macOS and BSD paths are
written from documented behaviour and have **never been executed** — this
machine has no WSL and no second host. Windows is the only host where the build
and `tools/bootcheck.ps1` have actually been run green.


## run.ps1 is at the repo root, so tool sweeps miss it

It is a `.ps1` but it does **not** live under `tools/`, and it went stale in
five ways at once while every tool beside it was fixed: hdb defaulting to
`build/fs.img` (which nothing builds any more, so the file simply does not
exist), a `-SchFS` switch built around the old arrangement where SchFS was a
secondary volume, a hardcoded QEMU path, `build\` backslash literals, and
`cd /d/DEV/SchOS` hardcoded into the build invocation -- which survived the
Schunix -> SchOS rename by luck and would break on any clone. Rewritten
2026-08-09. **When sweeping the tools, check the repo root too.**

## The stale-image trap bit again, and it looks exactly like a filesystem bug

A leftover headless QEMU holds `schos.img` and `build/schfs.img` open. On
Windows that makes `rm` fail with *Device or resource busy*, so `make` stops
**after** the kernel has relinked -- leaving a stale `schos.img` that boots the
previous kernel. The symptom this time was a PSOGM reading
`schfs root: no SchFS volume on the root device`, which reads as SchFS being
broken and is not: SchFS mounts cleanly on 1, 2 and 4 CPUs.

`kill %1` from Git Bash does not reliably kill a Windows QEMU. Use:

```sh
pwsh -NoProfile -Command "Get-Process qemu-system-x86_64 -ErrorAction SilentlyContinue | Stop-Process -Force"
```

A tell: `ls -l schos.img` showing anything other than **5,120,000 bytes**
(`dd count=10000`) means the image was not rewritten and is stale.

**Rule: before believing a boot failure, confirm no QEMU is running and that
schos.img was written by the build you think it was.**