---
name: schunix-build-environment
description: Schunix builds natively on Windows with clang/lld + mingw + Git Bash; WSL is gone because WSL2 needs Hyper-V
metadata: 
  node_type: memory
  type: project
  originSessionId: 9d8a2aef-bcf0-47a0-96c6-f706efab4a95
  modified: 2026-08-07T17:19:34.188Z
---

**Builds natively on Windows. WSL is no longer used at all.** WSL2 runs a real
Linux kernel in a Hyper-V VM, so it hard-requires virtualisation, and enabling
that puts the Hyper-V hypervisor under the whole machine — which demotes VMware
to running nested and slows the box down permanently. Nexoniarz will not enable
it, and that is a reasonable call.

`make` from **Git Bash** does everything. `run.ps1` builds natively too. The
toolchain, all already installed:

- **clang + ld.lld + llvm-objcopy/objdump** (`C:\Program Files\LLVM\bin`) —
  clang is a cross-compiler by construction, so `--target=x86_64-elf` builds the
  kernel and `--target=i386-elf` the bootloader. No cross-binutils needed.
- **mingw-w64 gcc** (`scoop install mingw`) for host tools — `tools/mkfs.c`
  needs `<unistd.h>`/`<dirent.h>`, which the Windows SDK lacks.
- **make** (`scoop install make`), plus Git Bash's perl/sed/dd/sha256sum.

`run.ps1` prepends all three directories itself, so it works from any shell.
The Makefile detects Windows via `uname -s` matching `MINGW*` and sets
`WINHOST`. Ports (musl/mksh/toybox) are **not** rebuilt on Windows — they are
Linux userland built by configure scripts, already staged in `sysroot/`, and
the Makefile says so out loud rather than skipping silently. Everything is a
no-op on Linux, so a Linux/VM build still works identically.

**Five latent bugs the move exposed**, all real, none Windows-specific — see
`docs/architecture/kernel-history.md` §8 for the two hardest:

1. `kernel.ld` named no `.ltext`/`.ldata`/`.lbss` — with `-mcmodel=large`, LLVM
   and GCC 13+ put nearly everything there, and orphan placement put them past
   `end`, so `kinit1(end,...)` handed the allocator live `.lbss`.
2. `uint64` was `unsigned long` — 64-bit on Linux, **32-bit on Windows** (LLP64).
   Host tools include the on-disk structs, so this would have silently written
   images with half-width inode fields. Now data-model-aware + `_Static_assert`.
3. `syscall_entry` used `%fs:(0)` as scratch — that is the **TCB self-pointer**.
   GCC's direct `%fs:-8` TLS never reads it; clang materialises the TP from it.
4. `_start` read `argc`/`argv` via `register ... asm("rdi")`, which is only
   guaranteed for inline-asm operands. clang read uninitialised stack. Now
   `lib/start.S`.
5. lld needs `--image-base=0` for anything linked below 0x400000, and
   `-m elf_x86_64` on `ld -r -b binary`.

**When a symptom moves as you add printfs, stop printing and use the
watchpoint.** QEMU `-S -gdb tcp::26000` plus mingw's gdb (`hbreak`, then
`watch`) named the offending instruction on the first run after three rounds of
cprintf had failed. See [[schunix-verify-by-driving-shell]].