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>
---
 PROJECT_CONTEXT.md   |  2 +-
 doc/HOWTO.md         | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 scripts/build_win.sh | 20 ++++++++++++++-----
 3 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 672e18e..8b81c28 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -38,7 +38,7 @@
 - **3D:** Hybrid SDF/rasterization with BVH. Binary scene loader. Blender pipeline.
 - **Effects:** CNN post-processing: CNNEffect (v1) and CNNv2Effect operational. CNN v2: sigmoid activation, storage buffer weights (~3.2 KB), 7D static features, dynamic layers. Training stable, convergence validated.
 - **Tools:** CNN test tool operational. Texture readback utility functional. Timeline editor (web-based, beat-aligned, audio playback).
-- **Build:** Asset dependency tracking. Size measurement. Hot-reload (debug-only).
+- **Build:** Asset dependency tracking. Size measurement. Hot-reload (debug-only). WSL (Windows 10) supported: native Linux build and cross-compile to `.exe` via `mingw-w64`.
 - **Sequence:** DAG-based effect routing with explicit node system. Python compiler with topological sort and ping-pong optimization. 10 effects operational (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D, Flash, PeakMeter, Scene1). Effect times are absolute (seq_compiler adds sequence start offset). See `doc/SEQUENCE.md`.
 - **Testing:** **35/35 passing**. Fixed intermittent SIGTRAP in effect lifecycle tests.
 
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
diff --git a/scripts/build_win.sh b/scripts/build_win.sh
index c1732f0..da75748 100755
--- a/scripts/build_win.sh
+++ b/scripts/build_win.sh
@@ -24,12 +24,22 @@ cp third_party/windows/lib/wgpu_native.dll build_win/
 
 # Copy MinGW DLLs (pthread, etc.)
 echo "Copying MinGW DLLs..."
-MINGW_BIN=$(dirname $(find /opt/homebrew -name "libwinpthread-1.dll" | grep x86_64 | head -n 1))
-if [ -d "$MINGW_BIN" ]; then
-    cp "$MINGW_BIN/libwinpthread-1.dll" build_win/
-    cp "$MINGW_BIN/libgcc_s_seh-1.dll" build_win/ 2>/dev/null || true
-    cp "$MINGW_BIN/libstdc++-6.dll" build_win/ 2>/dev/null || true
+if [[ "$(uname)" == "Darwin" ]]; then
+    MINGW_SEARCH_ROOTS="/opt/homebrew"
 else
+    # Linux / WSL: mingw-w64 installed via apt
+    MINGW_SEARCH_ROOTS="/usr/x86_64-w64-mingw32 /usr/lib/gcc/x86_64-w64-mingw32"
+fi
+COPIED=0
+for dll in libwinpthread-1.dll libgcc_s_seh-1.dll libstdc++-6.dll; do
+    src=$(find $MINGW_SEARCH_ROOTS -name "$dll" 2>/dev/null | head -n 1)
+    if [ -n "$src" ]; then
+        cp "$src" build_win/
+        echo "  Copied: $dll"
+        COPIED=$((COPIED+1))
+    fi
+done
+if [ "$COPIED" -eq 0 ]; then
     echo "Warning: Could not find MinGW DLLs. You might need them to run the exe."
 fi
 
-- 
cgit v1.2.3