From c906cb0e048ef7cd32f636f1692a0c72a5d206b7 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 23 Feb 2026 09:16:54 +0100
Subject: docs(build): add WSL (Windows 10) build support and documentation

- build_win.sh: platform-aware MinGW DLL search (macOS Homebrew vs Linux apt paths)
- HOWTO.md: new WSL section covering native Linux build and Windows cross-compile
- PROJECT_CONTEXT.md: note WSL support in Build status

handoff(Gemini): WSL native + cross-compile build support added.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 doc/HOWTO.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

(limited to 'doc')

diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index a31ea3a..097f2fa 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -66,6 +66,61 @@ See `doc/HEADLESS_MODE.md`.
 ```
 Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.
 
+### WSL (Windows Subsystem for Linux)
+
+Requires **WSL2** with a Ubuntu/Debian distro. Two modes:
+
+#### Mode 1: Native Linux Build
+
+Install system packages:
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    build-essential cmake git python3 \
+    libglfw3-dev libxinerama-dev libxcursor-dev libxi-dev libxrandr-dev
+```
+
+Install `wgpu-native` (no apt package; download prebuilt from GitHub):
+```bash
+curl -L -o wgpu_linux.zip \
+  https://github.com/gfx-rs/wgpu-native/releases/download/v0.19.4.1/wgpu-linux-x86_64-release.zip
+unzip wgpu_linux.zip -d wgpu_tmp
+sudo cp wgpu_tmp/libwgpu_native.so /usr/local/lib/
+sudo cp wgpu_tmp/wgpu.h wgpu_tmp/webgpu.h /usr/local/include/
+sudo ldconfig
+rm -rf wgpu_linux.zip wgpu_tmp
+```
+
+Build and run:
+```bash
+cmake -S . -B build
+cmake --build build -j4
+./build/demo64k
+```
+
+> **Note:** Display output requires WSLg (built into Windows 11; also available on
+> updated Windows 10 builds via the Microsoft Store WSL update). Vulkan GPU
+> passthrough must be enabled — check `wsl --version` to confirm WSLg is active.
+
+#### Mode 2: Cross-Compile Windows `.exe` from WSL
+
+Install the MinGW-w64 cross-compiler:
+```bash
+sudo apt-get install -y mingw-w64
+```
+
+Fetch prebuilt Windows libraries (GLFW, wgpu-native DLLs):
+```bash
+./scripts/fetch_win_deps.sh
+```
+
+Build:
+```bash
+./scripts/build_win.sh
+```
+
+Output: `build_win/demo64k.exe` — copy to Windows and run directly.
+
 ---
 
 ## Testing
-- 
cgit v1.2.3