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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2

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 `<unistd.h>` and `<dirent.h>`,

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)

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 <nixpkgs> { } }:
+
+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 <unistd.h> and <dirent.h>.
+    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"
+  '';
+}