From 6c42ab3b1a083e147b7b24413b586921c331b56e Mon Sep 17 00:00:00 2001 From: Nexoniarz Date: Sat, 12 Sep 2026 18:31:34 +0200 Subject: [PATCH] build: a nix shell, because the loader is the one thing gcc cannot build make falls back to the GNU toolchain when clang is absent, and that works for the kernel. It does not work for the UEFI loader: BOOTX64.EFI is PE/COFF and wants clang plus lld-link, so a machine with only gcc gets a kernel that builds and a loader that silently stays whatever it already was. That is not hypothetical -- it is what left a stale boot splash on this tree for half a day. The mask in include/logo.h was the new mark, the kernel drew it, and the loader kept drawing one compiled months earlier because nothing could relink it and nothing said so. shell.nix declares everything docs/guides/building.md lists, and building.md gains a NixOS section saying why using it matters rather than just how. Verified: with clang 21.1.8 and LLD 21.1.8 the loader relinks and the splash draws Shift in metal, screendumped from the framebuffer rather than inferred. Pinned to the host's nixpkgs rather than a flake input, deliberately. This is a convenience for a development machine, not a reproducibility claim; if it ever needs to be the latter it wants a flake and should say so. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2 --- docs/guides/building.md | 19 ++++++++++++++++ docs/guides/layout.md | 1 + shell.nix | 48 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 shell.nix diff --git a/docs/guides/building.md b/docs/guides/building.md index a76eb6c..f785026 100644 --- a/docs/guides/building.md +++ b/docs/guides/building.md @@ -22,6 +22,25 @@ make qemu # build and boot it | `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` | +On NixOS, `nix-shell` supplies every row above — see below. + +## NixOS + +```sh +nix-shell # then: make, make qemu, make iso +``` + +`shell.nix` in the repository root declares the lot. Worth using rather than +assembling it by hand, for one specific reason: **`make` falls back to the GNU +toolchain for the kernel but the UEFI loader genuinely cannot be built without +clang and `lld-link`.** A machine with only gcc therefore produces a kernel that +builds and a loader that silently stays whatever it already was — which left a +stale boot splash on this tree for half a day before anyone looked at the +screen rather than the build output. + +PowerShell is the one thing the shell does not supply, and `tools/windows/` +needs it. See the note at the end of this file. + 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 `` and ``, diff --git a/docs/guides/layout.md b/docs/guides/layout.md index a8dfbcc..d2f8e28 100644 --- a/docs/guides/layout.md +++ b/docs/guides/layout.md @@ -47,6 +47,7 @@ schos/ │ can be re-fetched sparsely. Copying from it is governed by │ the per-file licence check in docs/licensing.md §3 -- │ NetBSD is not uniformly licensed. +├─ shell.nix NixOS development shell: the whole toolchain in one file ├─ docs/ architecture/ what it is plan/ what's next │ guides/ how to work history/ why it's like this └─ build/ ALL generated output (see below) diff --git a/shell.nix b/shell.nix new file mode 100644 index 0000000..a51936c --- /dev/null +++ b/shell.nix @@ -0,0 +1,48 @@ +# A development shell with everything docs/guides/building.md asks for. +# +# nix-shell # then: make, make qemu, make iso +# +# Why this exists: the UEFI loader is the one part that genuinely cannot be +# built without clang and lld. `make` falls back to the GNU toolchain for the +# kernel, so a machine with only gcc gets a kernel that builds and a loader that +# silently stays whatever it was -- which is exactly the failure that left a +# stale boot splash on this tree for half a day. +# +# Pinned to whatever nixpkgs the host is on rather than to a flake input, on +# purpose: this is a convenience for one developer's machine, not a +# reproducibility claim. If it ever needs to be the latter it wants a flake. +{ pkgs ? import { } }: + +pkgs.mkShell { + name = "schos"; + + nativeBuildInputs = with pkgs; [ + # The cross-compiler, and the reason this file exists. clang targets + # bare-metal ELF, 16-bit code and PE/COFF from one install; lld-link is what + # produces BOOTX64.EFI. + clang + lld + llvm # llvm-objcopy, llvm-objdump + + # The host compiler, for tools/ -- mkfs, mkschfs, the SchFS suites. Must be + # a real Unix compiler: those need and . + gcc + + gnumake + perl # generates the interrupt vector table + python3 # boot logo, crash-screen QR, mklogo + + qemu # make qemu, and every test harness + OVMF # firmware for the UEFI path; the Makefile searches for it + + xorriso # make iso + mtools # ESP staging + curl gnutar # fetching ports + ]; + + shellHook = '' + echo "schos: clang $(clang --version | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')," \ + "$(qemu-system-x86_64 --version | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')" + echo " make | make qemu | make schfs-check | make iso" + ''; +}