From b533d35f9501fbd1a57fa8e52622e2a927a5546f Mon Sep 17 00:00:00 2001 From: bsncubed Date: Thu, 30 Jul 2026 21:58:02 +1000 Subject: [PATCH] docs: document the OpenGL requirement and the RDP workaround haul compiles cleanly on Windows and then fails at startup inside an RDP session, because Remote Desktop's display driver provides no usable OpenGL and Fyne needs 2.1+. Same for Hyper-V, VMs without 3D, and Microsoft Basic Display Adapter. Documents deploying Mesa's llvmpipe renderer beside haul.exe, and two things that are easy to get wrong: all ~19 DLLs from x64 are needed rather than just opengl32.dll, since that file is now only a front-end for the others; and a local opengl32.dll shadows the system one, so it forces software rendering even on machines with a working GPU. Also adds OpenGL to the runtime requirements table, which only mentioned needing a display server. Verified in an RDP session. Co-Authored-By: Claude Opus 5 --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bf8e84c..783dda7 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ To **run** haul: | ---------------------- | ------------------------------------------------------- | | The system `ssh` client | Saved-host connections call `ssh -G ` to resolve the effective config, so ssh_config semantics are never re-implemented | | A graphical desktop | haul is a GUI application; it needs a display server | +| **OpenGL 2.1 or newer** | Fyne renders through OpenGL. Remote Desktop sessions, VMs without 3D acceleration, and machines running Microsoft Basic Display Adapter don't provide it — see [Remote Desktop and VMs](#running-over-remote-desktop-or-in-a-vm) | | An SFTP-capable server | Transfers use the SFTP subsystem — see [Scope](#scope) | ## Building @@ -200,8 +201,61 @@ If you would rather use the Makefile, install `make` inside the MSYS2 shell `-H=windowsgui` yourself, for example `make build LDFLAGS="-s -w -H=windowsgui"`. -Unlike Linux, Windows needs no graphics development packages: OpenGL is part of -the operating system. +Unlike Linux, Windows needs no graphics development *packages* to build: OpenGL +ships with the operating system. Getting a usable OpenGL at **run** time is a +separate matter — see below. + +### Running over Remote Desktop (or in a VM) + +A build that compiles perfectly will still fail to start in an RDP session with: + +``` +Fyne error: window creation error +Cause: APIUnavailable: WGL: The driver does not appear to support OpenGL +``` + +This is not a haul fault — any OpenGL application fails the same way. Fyne needs +OpenGL 2.1+, and Remote Desktop's display driver doesn't provide it. The same +applies to Hyper-V and to VMs without 3D acceleration, and to any machine using +Microsoft Basic Display Adapter. + +The fix is Mesa's software OpenGL renderer (llvmpipe), deployed just for haul: + +1. Download a `mesa3d--release-msvc.7z` from + [mesa-dist-win releases](https://github.com/pal1000/mesa-dist-win/releases). + It's a `.7z`, so you'll need 7-Zip (`winget install 7zip.7zip`) to extract it. +2. Open the extracted **`x64`** folder (not `x86`). +3. Copy **every DLL in it** — around 19 files — into the same folder as + `haul.exe`. + +``` +bin\ + haul.exe + opengl32.dll + libgallium_wgl.dll + ...and the rest of x64\ +``` + +Verified working in an RDP session on 2026-07-30. + +Three things worth knowing: + +- **Copy all of the DLLs, not just `opengl32.dll`.** In current Mesa builds that + file is a thin front-end that loads `libgallium_wgl.dll` and others alongside + it. Taking it on its own produces a DLL that can't load its dependencies, and + haul fails exactly as if you'd done nothing. +- **A local `opengl32.dll` always wins over the system one**, because Windows + searches the executable's own directory first. So these DLLs force software + rendering *unconditionally* — including on a machine with a perfectly good GPU. + If you use haul both locally and over RDP, keep two copies: one folder with the + Mesa DLLs, one without. +- **Don't run `systemwidedeploy.cmd`** if you see it in the archive. That + installs Mesa for every OpenGL application on the machine; copying files beside + `haul.exe` keeps the change contained to haul. + +Software rendering is slower than a GPU, but haul draws two tables and some text +— it's entirely adequate. The headless Linux target does the same thing via +`LIBGL_ALWAYS_SOFTWARE=1` in `make run-xvfb`. ### Make targets