WSLg GPU: NVIDIA userland install + cairo-software fallback toggle

Two coupled changes per operator 2026-05-10 directive
("WSLg + GPU-PV ... NVIDIA Vulkan ICD; option 1 default + option 3
selectable fallback").

1. /usr/libexec/mios/install-nvidia-wsl-userland.sh (NEW): installs
   nvidia-driver-libs from NVIDIA's official CUDA repo
   (developer.download.nvidia.com/compute/cuda/repos/fedoraN). Pulls:
     * /usr/share/vulkan/icd.d/nvidia_icd.x86_64.json
     * /usr/lib64/libGLX_nvidia.so.0 + libEGL_nvidia.so.0
     * libnvidia-gpucomp / libnvidia-ml RPM versions
     * egl-wayland / egl-gbm / egl-x11 platform implementations
   Userland-only -- excludes kmod-nvidia* / akmod-nvidia* (kernel
   modules don't apply on WSL; /dev/dxg already provides the kernel
   bridge). Self-detects WSLg via /dev/dxg + /mnt/wslg, exits
   cleanly on bare-metal / Hyper-V / OCI substrates. Idempotent.

   Caveat documented inline: NVIDIA's NATIVE Vulkan ICD enumerates
   no GPU under WSL because it expects /dev/nvidia* device nodes
   that WSL doesn't expose. Vulkan workloads still go through dzn.
   Why install anyway: nvidia-smi works; libGLX_nvidia is forward-
   compatible when WSL2 eventually exposes /dev/nvidia* or NVIDIA
   ships a /dev/dxg-aware Vulkan ICD; flatpak apps that probe for
   NVIDIA detection get a real vendor lib to point at.

2. /etc/profile.d/mios-wslg-gpu.sh: added MIOS_GPU_SOFTWARE=1
   toggle. Set in shell or ~/.config/environment.d/ to force
   cairo + llvmpipe (CPU-only rendering). Slow but always
   produces visible content -- escape hatch for apps where the
   d3d12 / dzn paths still fail. Default behavior unchanged
   (d3d12 + GL renderer).

build-mios.ps1: added overlay-phase invocation of the install
script after the [desktop].flatpaks pass. Runs as root inside the
dev VM via wsl.exe; surfaces install-script's [ok]/[skip]/[warn]
lines through Log-Ok / Log-Warn so the install summary reflects
NVIDIA stack state.

Verified live on running podman-MiOS-DEV: install completes,
nvidia_icd.x86_64.json + libGLX_nvidia.so.0 land at expected
paths. Vulkan loader still picks dzn for actual rendering (per
the WSL caveat above) but the stack is in place for the day WSL
gains /dev/nvidia* visibility.

Author: Kabuki94

etc/profile.d/mios-wslg-gpu.sh

@@ -23,6 +23,20 @@
 
 [ -d /mnt/wslg ] || return 0
 
+# ── Cairo / software-rendering fallback toggle ───────────────────
+# Set MIOS_GPU_SOFTWARE=1 to force CPU-only rendering (cairo +
+# llvmpipe). Slow but always produces visible content -- useful
+# when dzn / d3d12 / NVIDIA paths are all failing for a specific
+# app. Operator can flip per-shell or persist via
+# ~/.config/environment.d/. Default (unset) = hardware-accelerated
+# d3d12 path below.
+if [ "${MIOS_GPU_SOFTWARE:-0}" = "1" ]; then
+    export GALLIUM_DRIVER="${GALLIUM_DRIVER:-llvmpipe}"
+    export LIBGL_ALWAYS_SOFTWARE=1
+    export GSK_RENDERER="${GSK_RENDERER:-cairo}"
+    return 0 2>/dev/null || exit 0
+fi
+
 # ── Mesa / GL ────────────────────────────────────────────────────
 # d3d12 = the Mesa Gallium driver that targets WSLg's WDDM via
 # /dev/dxg. Far more reliable than dzn (Vulkan) for typical GTK

usr/libexec/mios/install-nvidia-wsl-userland.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# /usr/libexec/mios/install-nvidia-wsl-userland.sh
+#
+# Install NVIDIA's Vulkan ICD + GLX/EGL userspace libs for WSLg
+# dev-VM hosts. Called by build-mios.ps1's Quadlet/overlay phase
+# AND idempotent-callable from `mios install-gpu` for live re-runs.
+#
+# What this gets you:
+#   * /usr/share/vulkan/icd.d/nvidia_icd.x86_64.json
+#   * /usr/lib64/libGLX_nvidia.so + libEGL_nvidia.so + libGLESv2_nvidia
+#   * libnvidia-ml + libnvidia-gpucomp (already provided by WSL drop,
+#     installing the RPM versions is harmless and adds versioned symlinks)
+#   * egl-wayland + egl-gbm + egl-x11 (EGL platform implementations)
+#
+# What this does NOT do:
+#   * NO kernel-module install (kmod-nvidia / akmod-nvidia) -- the
+#     kernel module isn't applicable on WSL2; /dev/dxg is the kernel-
+#     mode bridge and it's already there.
+#   * NOT a full CUDA toolkit install -- libnvidia-ml is enough for
+#     `nvidia-smi` and PyTorch's CUDA detection. Operators wanting
+#     the full toolchain run `dnf install cuda-toolkit-X-Y` separately.
+#
+# Caveat: this installs NVIDIA's NATIVE Vulkan ICD which expects
+# /dev/nvidia* device nodes. WSL2 doesn't have those -- it has
+# /dev/dxg (WDDM) instead. So the NVIDIA Vulkan ICD doesn't enumerate
+# any GPU under WSL; Vulkan workloads still go through Microsoft's
+# `dzn` ICD (Direct3D12 translation). Why install NVIDIA libs anyway?
+#
+#   1. Compute / CUDA workloads work via libcuda + libnvidia-ml
+#      (Microsoft's WSL drop) regardless of NVIDIA Vulkan availability.
+#   2. nvidia-smi becomes available so the operator can verify GPU
+#      health from inside the dev VM.
+#   3. Flatpak apps that bundle libGLX_nvidia detection get a real
+#      (if non-functional under WSL) vendor lib to point at, avoiding
+#      "no NVIDIA driver detected" warnings on launch.
+#   4. Forward-compatible: when WSL2 eventually exposes /dev/nvidia*
+#      (or NVIDIA ships a WSL-aware Vulkan ICD that targets /dev/dxg),
+#      this stack is already in place.
+#
+# Idempotent + safe to re-run: dnf install of already-present pkgs
+# is a no-op; repo add with --overwrite refreshes the .repo file.
+#
+# Operator override: set MIOS_SKIP_NVIDIA_INSTALL=1 to skip entirely.
+
+set -e
+
+if [ "${MIOS_SKIP_NVIDIA_INSTALL:-0}" = "1" ]; then
+    echo "  [skip] MIOS_SKIP_NVIDIA_INSTALL=1; not installing NVIDIA userland."
+    exit 0
+fi
+
+# Gate on WSLg presence -- this script is for WSLg dev VMs only.
+if [ ! -d /mnt/wslg ] && [ ! -c /dev/dxg ]; then
+    echo "  [skip] not WSLg (no /mnt/wslg + no /dev/dxg); NVIDIA WSL userland not applicable."
+    exit 0
+fi
+
+# Detect upstream Fedora version. MiOS-branded os-release sets
+# VERSION_ID to the MiOS version; PLATFORM_ID preserves the Fedora
+# upstream as "platform:fXX".
+fedver=$(. /etc/os-release; echo "$PLATFORM_ID" | sed -E 's/^.*:f([0-9]+)$/\1/')
+[ -z "$fedver" ] && fedver=$(. /etc/os-release; echo "${VERSION_ID:-44}")
+echo "  Fedora upstream: $fedver"
+
+# Probe NVIDIA CUDA repo URLs. Try the detected fedora version first,
+# fall back to nearby versions if 404 (NVIDIA publishes per-Fedora-
+# version repos on a release-by-release basis).
+repo_url=""
+for v in "$fedver" 44 43 42 41 40; do
+    [ -z "$v" ] && continue
+    cand="https://developer.download.nvidia.com/compute/cuda/repos/fedora${v}/x86_64/cuda-fedora${v}.repo"
+    code=$(curl -fsI -o /dev/null -w "%{http_code}" "$cand" 2>/dev/null || true)
+    if [ "$code" = "200" ]; then
+        echo "  NVIDIA CUDA repo: fedora${v} ($cand)"
+        repo_url="$cand"
+        break
+    fi
+done
+if [ -z "$repo_url" ]; then
+    echo "  [warn] no NVIDIA CUDA repo reachable for Fedora ${fedver} or fallbacks; skipping."
+    exit 0
+fi
+
+dnf config-manager addrepo --from-repofile="$repo_url" --overwrite >/dev/null 2>&1 || true
+
+# Install userland-only. Excludes are defensive against weak-deps
+# pulling in a kernel-module package; --setopt=install_weak_deps=False
+# is also belt-and-suspenders.
+dnf install -y --setopt=install_weak_deps=False \
+    -x 'kmod-nvidia*' \
+    -x 'akmod-nvidia*' \
+    -x 'nvidia-driver-cuda' \
+    -x 'nvidia-driver-NvFBCOpenGL' \
+    nvidia-driver-libs 2>&1 | tail -5
+
+# Verify install landed.
+if [ -e /usr/share/vulkan/icd.d/nvidia_icd.x86_64.json ] \
+    && [ -e /usr/lib64/libGLX_nvidia.so.0 ]; then
+    echo "  [ok] NVIDIA WSL userland installed:"
+    echo "         vulkan ICD: /usr/share/vulkan/icd.d/nvidia_icd.x86_64.json"
+    echo "         GLX/EGL:    /usr/lib64/libGLX_nvidia.so.0 + libEGL_nvidia.so.0"
+else
+    echo "  [warn] install completed but expected files missing -- inspect dnf output above."
+    exit 1
+fi