651899220c
1449 lines of boot/bios/, tools/sign.pl and tools/padstage2.pl, plus the build rules, the disk image and the ISO entry that existed to carry them. Everything since roughly 2012 boots UEFI, and CSM -- the firmware-side BIOS emulation that lets a legacy loader run on such a machine at all -- has been going away since Intel dropped support for it in 2020. So this is not a path being retired early; it is one whose remaining hardware is already the exception. The cost was never the code, it was the tax on everything near it. Stage 2 had a 65-sector ceiling it overflowed silently -- 25440 bytes against 24576 -- and because the kernel is written at sector 1 + STAGE2_SECTORS, an overflowing loader was overwritten by the very kernel it was loading. The resolution list could not be shared with UEFI either: VBE mode setting is INT 10h, so matching it needed unreal mode, which is the riskiest code in the tree for a feature that already worked elsewhere. What replaces schos.img is the staged ESP, handed to QEMU as a virtual FAT volume. That is a development arrangement and not an installable disk; a real GPT image with a real FAT partition is the installer's job, and until it exists nothing here writes a disk a machine boots unaided. Secure Boot is untouched too -- the loader is unsigned. The ISO keeps one El Torito entry, the FAT image holding loader and kernel. It never booted from a USB stick via BIOS anyway: the firmware presents the stick as a hard disk while stage2main.c read the kernel back over ATAPI. The 32-bit multiboot entry in entry.S now has no caller and is left in place. Deleting kernel entry code is its own change with its own way of failing silently, and it should not ride along with this one. Ported with it: run.ps1, the six screenshot tools, and schcom_test.sh, each with its own OVMF varstore copy so no run inherits another's UEFI variables. Two things this shook out. OVMF now belongs in `all`: nothing boots without firmware, `make clean` wipes build/ including the copy fetched from the host, and a clean followed by a build left every run script throwing. And it cannot be listed as a prerequisite at the top of the file -- make expands prerequisites when it reads the line, and $(OVMF_CODE) is defined further down, so naming it there appends nothing and says nothing. Verified from a clean tree: 110 [ok] and no failures on the full suite, the ISO boots with no hard disk attached, schfs-check passes, schcom's end-to-end pixel test passes, and fbshot captures a real 1280x800 frame.
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
|
# Building SchOS
|
|
|
|
Supported hosts: **Linux, macOS, FreeBSD/OpenBSD/NetBSD, and Windows** (under
|
|
Git Bash or MSYS2). The build is developed from both Windows and Linux, so a
|
|
change that only works on one of them is a bug.
|
|
|
|
```sh
|
|
make # kernel + UEFI loader + root filesystem
|
|
make qemu # build and boot it
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
| Need | Why | Windows | Linux | macOS | BSD |
|
|
|---|---|---|---|---|---|
|
|
| `clang`, `ld.lld`, `llvm-objcopy`, `llvm-objdump` | cross-compiles the kernel, the 16/32-bit boot code, and musl userland | LLVM installer | `clang lld llvm` | `brew install llvm` | `pkg install llvm` |
|
|
| `make` | — | Git Bash | `make` | Xcode CLT | `gmake` |
|
|
| `perl` | generates the interrupt vector table | Git Bash | usually present | present | `pkg install perl5` |
|
|
| `python3` | boot logo, crash-screen QR | python.org (`python`) | `python3` | `brew install python` | `pkg install python3` |
|
|
| `qemu-system-x86_64` | running and testing | `scoop install qemu` | `qemu-system-x86` | `brew install qemu` | `pkg install qemu` |
|
|
| `curl`, `tar` | fetching ports | Git Bash | present | present | present |
|
|
| `xorriso` **or** `mkisofs` | `make iso` only | `scoop install cdrtools` | `xorriso` | `brew install xorriso` | `pkg install xorriso` |
|
|
|
|
A host C compiler (`cc`) is also needed, for the tools that build the disk
|
|
images. On Windows that must be **mingw-w64's gcc**, not clang: clang defaults
|
|
to an MSVC target there, and `tools/mkfs.c` needs `<unistd.h>` and `<dirent.h>`,
|
|
which the Windows SDK does not have.
|
|
|
|
## Why clang rather than a cross-gcc
|
|
|
|
clang is a cross-compiler by construction, so one ordinary LLVM install targets
|
|
everything this tree needs — bare-metal ELF, code linked below one megabyte, and
|
|
Linux/musl userland — from any host. A cross binutils+gcc would be a day of
|
|
setup per platform that then rots, and on macOS it means brewing
|
|
`x86_64-elf-gcc` before anything builds at all.
|
|
|
|
The Makefile selects clang+lld whenever both are on `PATH`. To force the GNU
|
|
toolchain instead:
|
|
|
|
```sh
|
|
make USE_GNU=1 # needs a cross toolchain that emits x86_64 ELF
|
|
make USE_GNU=1 TOOLPREFIX=x86_64-elf-
|
|
```
|
|
|
|
## Testing
|
|
|
|
```sh
|
|
tools/windows/bootcheck.ps1 # boots, drives the shell, asserts on output
|
|
tools/windows/bootcheck.ps1 -Tty -Ps # plus terminal behaviour and process listing
|
|
make schfs-check # SchFS unit, object and image suites
|
|
```
|
|
|
|
`bootcheck` is PowerShell, and PowerShell 7 (`pwsh`) runs on Linux, macOS and
|
|
the BSDs as well as Windows — `brew install powershell`, or your distribution's
|
|
`powershell` package. It finds QEMU on `PATH`.
|
|
|
|
Booting to a prompt proves nothing on its own: a filesystem can mount and still
|
|
fail the first real command, which has happened here. `bootcheck` types commands
|
|
at the serial console and greps the transcript for the answers they should
|
|
produce.
|
|
|
|
## Ports
|
|
|
|
`musl`, `toybox` and `mksh` are built from source into `sysroot/`. **This does
|
|
not work on a Windows host** — `make` prints `ports: skipped` and uses whatever
|
|
is already staged in `sysroot/`. Building them needs a Linux host (or any other
|
|
Unix); do it once and the staged result serves the Windows builds.
|
|
|
|
## Where the tools live
|
|
|
|
`tools/` is grouped by what runs the file, so it is obvious at a glance which
|
|
tools a given host can use:
|
|
|
|
```
|
|
tools/
|
|
windows/ .ps1 PowerShell (pwsh runs these on Linux and macOS too)
|
|
posix/ .sh shell
|
|
python/ .py
|
|
*.c host programs -- compiled by the build, run everywhere
|
|
*.pl perl, likewise
|
|
```
|
|
|
|
The `.c` and `.pl` files stay at the top level because they are not
|
|
host-specific: the build compiles or invokes them on every platform.
|
|
|
|
A script that needs the repo root derives it from its own location, so anything
|
|
moved between these directories has to have that adjusted — the PowerShell tools
|
|
use `Split-Path (Split-Path $PSScriptRoot -Parent) -Parent`, two levels up.
|
|
|
|
## Known host differences, already handled
|
|
|
|
Listed because they are the shape of the next such bug, not because anything is
|
|
outstanding:
|
|
|
|
- `<sys/sysmacros.h>` is glibc/musl only. macOS and the BSDs take `major()` and
|
|
`minor()` from `<sys/types.h>`.
|
|
- `sha256sum` exists on Linux and Git Bash; macOS has `shasum -a 256`,
|
|
FreeBSD/NetBSD `sha256`, OpenBSD `cksum -a sha256`. `tools/posix/sha256check.sh`
|
|
finds whichever is present.
|
|
- `nproc` is coreutils, so absent on macOS and BSD, where it is
|
|
`sysctl -n hw.ncpu`.
|
|
- In the PowerShell tools, path literals must use forward slashes:
|
|
`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:
|
|
|
|
```sh
|
|
tools/posix/memory-sync.sh status
|
|
tools/posix/memory-sync.sh export # after a session that learned something; then commit
|
|
tools/posix/memory-sync.sh import # after cloning or pulling elsewhere
|
|
```
|