Windows Self-Host (current state and roadmap)

This roadmap tracks bringing kit up as a self-hosted Windows toolchain: cross-compiling the kit binary into a PE/COFF kit.exe and running kit cc (AOT) and kit run (JIT) natively on Windows. The hosted target profile, sysroot mechanics, and VM are described in ../WINDOWS.md; the ABI work is in [windows-abi context]; this document tracks the self-host goal, the baseline already in tree, and the genuinely-open follow-ups.

Targets are PE/COFF, 64-bit only: aarch64-windows (the reference, and what runs natively on the Apple-silicon ARM64 Win11 VM) and x86_64-windows (runs via the in-box x64 emulator on the same VM). The hosted profile is mingw-w64 UCRT via llvm-mingw (not MSVC): kit advertises __MINGW32__/__MINGW64__, never _MSC_VER.

Baseline (done — context, not planned work)

Cross-build + native cc + native JIT all work on aarch64-windows, verified on the VM.

• Cross-build: scripts/windows_cross.sh aarch64 builds kit.exe (PE32+ console, ~20 MB) with the host build/kit as the cross-compiler against the llvm-mingw UCRT sysroot, overriding HOST_OS=windows HOST_ARCH=aarch64 so mk/env.mk selects driver/env/windows.c. (Windows can't bootstrap natively — no seed C compiler in the VM — so the binary is cross-produced on the dev host; contrast the native Linux/FreeBSD bootstraps.)
• kit cc: compiles + links real C programs natively on the VM (hello.c → a hello.exe that prints and returns the right exit code), compiling libkit_rt on demand.
• kit run (JIT): executes self-contained programs (compute, data/globals), external calls (rand), and libc I/O via dlsym (puts).
• Toy corpus on the VM (native kit.exe, compare .expected):
  • AOT (kit cc compile + link + execute): 166 / 166 pass, 0 miscompile, 0 crash, at -O0.
  • JIT (kit run): 166 / 166 — the printf-family and thread-local gaps (§1) are fixed; the two thread-local cases (141, 142) now return their values (43, 134).

The items below are what is not yet done. The concrete open bugs/blockers are collected first; the numbered sections are the larger roadmap items.

Open bugs / blockers

Concrete defects surfaced during bring-up, each blocking a roadmap item below.

• x64 self-host kit.exe crashes (0xC0000005) on most subcommands — OPEN. The x64 kit.exe loads and dispatches (help, hash work), but nm/size/cpp/as crash. Suspected root cause: the kit.exe binary itself still imports __intrinsic_setjmp from api-ms-win-crt-private-l1-1-0.dll (a CRT-private api-set that may not load cleanly on Prism). Despite the two-archive rt placement fix (§2) that resolves the issue for kit-compiled programs, something in kit.exe's own link is still pulling the COFF WEAK_EXTERNAL _setjmp → __intrinsic_setjmp alias from libucrt.a. Exact trigger still under investigation (the strong _setjmp from libkit_rt.a does appear defined before libucrt.a scans, yet the import stub is pulled anyway — possibly via __imp___intrinsic_setjmp or a symbol not yet traced).

2. x86_64-windows parity

aarch64-windows is the reference. x64 codegen now shares the large-frame stack-probe gate (§Baseline) via abi_stack_probe_interval, and the cross-link now succeeds end to end.

What landed (this cycle):

• rt/lib/coro/x86_64_win.c now exports strong _setjmp and _setjmpex globals (in addition to the existing weak setjmp). mingw x64's setjmp.h expands setjmp(BUF) to _setjmp(BUF, frame) and declares _setjmp as a COFF WEAK_EXTERNAL aliasing __intrinsic_setjmp from api-ms-win-crt-private-l1-1-0.dll — a private CRT api-set that fails to load on some runtimes (e.g. 0xC0000139 on Prism). Providing a strong _setjmp in rt preempts the alias.

• driver/cmd/cc.c places libkit_rt.a at two positions in the Windows link order:

  • rt#1: immediately before the hosted after group (before libmingw32.a, libucrt.a, …). This ensures _setjmp is in defined before libucrt.a's lazy-pull loop runs, so the WEAK_EXTERNAL member that introduces __intrinsic_setjmp is never pulled.
  • rt#2: before crtend.o only (the original position). libucrt.a pulls libc members (printf, malloc, …) that contain large GCC-compiled stack frames whose ___chkstk_ms undefs appear only after libucrt.a's own scan completes; the second rt entry catches those late undefs. Because archive scanning is lazy, no symbol is ever defined twice.

• driver/env/windows.c: fixed a forward-reference to driver_join_path (used at its call site before the definition appeared in the same file).

VM verification status (Prism, Win11 25H2 ARM64):

• x64 kit.exe loads and dispatches (kit with no args prints the multitool help). ✓
• x64 kit.exe hash works (compute + file I/O, exit 0, correct digest). ✓
• A kit-compiled x64 non-setjmp hosted program (printf hello) runs and returns its exit code. ✓
• A kit-compiled x64 setjmp program runs end-to-end. ✓ (Fixed by the strong _setjmp in rt + two-archive placement.)
• x64 Toy AOT corpus (kit cc compile + link + execute, compare .expected): 164 / 165 at both -O0 and -O1. The one failure (118_decl_extra_attrs) is an aarch64-only ADRP-range link issue — pre-existing, not an x64 regression.
• The x64 self-host kit.exe itself is not yet usable as a compiler on the VM — nm/size/cpp/as crash (see Open bugs). Running the Toy AOT corpus through a native x64 kit.exe is blocked on fixing the __intrinsic_setjmp import.
• Known x64-windows codegen gaps already on file (from the toy VM lanes): 36/37 *sret tail-call crash at -O1, and 118_decl_extra_attrs ADRP-range link is aarch64-only. Re-confirm against a native x64 kit.exe once the above are triaged.

3. A committed "compile-on-VM" test lane

test/toy/vm.sh windows today cross-compiles the toy cases on the host and only executes on the VM, so it cannot catch self-host compile bugs (the §Baseline stack-probe crash, for one, was invisible to it). The native self-host path (kit.exe compiling on the VM) has been exercised ad hoc. Generalize it into a committed lane (e.g. test/toy/vm.sh windows --native or a new harness) that ships the case sources + a <bindir>/support/rt + the mingw sysroot to the VM, compiles with kit.exe there, runs, and compares .expected. Gotchas to bake in:

• PowerShell Start-Process -PassThru without -Wait reports .ExitCode = 0 always — use a [Diagnostics.Process] with WaitForExit(ms) + .ExitCode, or & exe; $LASTEXITCODE with a Defender path exclusion. Likewise cmd %ERRORLEVEL% expands at parse time — use cmd /v:on + !ERRORLEVEL!.
• macOS tar adds AppleDouble ._* sidecars — ship case sources with COPYFILE_DISABLE=1 (same trap as the FreeBSD bootstrap).
• The mingw sysroot's <arch>-w64-mingw32/include is a symlink to generic-w64-mingw32/include; dereference (cp -RL) before shipping.

4. Distribution + default sysroot

• Ship the Windows distribution as <bindir>/support/rt (what kit install produces); rt now resolves from the real image path, so no cwd dependence.
• The Windows hosted profile requires --sysroot/KIT_SYSROOT (no default). Windows ships the runtime DLLs (ucrtbase.dll, the api-ms-win-crt-* api-sets, kernel32.dll) but no headers or import libs, so a sysroot is mandatory. Consider: bundling the mingw UCRT headers + import libs into the kit distribution (a baked sysroot), and/or teaching the COFF linker to synthesize imports directly from a system DLL's export table (drops the import-lib half of the sysroot, but the crt2.o startup + libmingwex helpers — __mingw_setjmp, __local_stdio_printf_options, … — still have no DLL home and would have to move into libkit_rt for Windows).

5. Windows 3-stage bootstrap

The self-host milestone: use the cross-built kit.exe on the VM to compile kit's own sources into a stage-2 kit.exe, then stage-3, and assert stage-2 == stage-3 byte-for-byte (cf. BOOTSTRAP.md, and the native-bootstrap analogs scripts/{linux,freebsd}_bootstrap.sh). Unblocked now that the large-frame stack-probe crash and the __FILE__ malformed UCN bug are fixed — kit.exe compiles + links + runs the full Toy AOT corpus (166/166) on the VM, and now compiles the rt tree on the VM cleanly (the on-demand kit cc rt build succeeds). The malformed UCN bug turned out to be a host-path stringization defect, not a self-compile codegen defect, so it does not threaten stage-2==stage-3 identity. Next: confirm kit.exe can compile the full libkit/driver source set on the VM, then add a scripts/windows_bootstrap.sh to drive the VM-side stages and the stage-2==stage-3 byte-identity check.

6. Debugger fault-guard / SEH on Windows

driver/env/windows.c's driver_run_with_crash_guard is a no-op on Windows (the POSIX path uses sigaction + sigsetjmp); a crashing kit run program takes down kit.exe instead of reporting on_crash. The dbg guarded_copy also relies on the VEH backstop rather than __try (kit's C frontend has no SEH). A proper vectored-exception-handler port would give kit run/kit dbg fault isolation on Windows.

Operational notes

• Build: scripts/windows_cross.sh [aarch64|x64] (needs make bin, the mingw sysroot via scripts/llvm_mingw_sysroot.sh prepare <arch>, and the rt variant). kit cc emits no -MMD depfiles, so the script wipes objects for a correct full rebuild each run.
• VM: scripts/windows_vm.sh boot|wait-ssh|run|ssh|stop (see ../WINDOWS.md). One ARM64 VM serves both arches.