From 47ad62bb84dbc3f6ea749c6a697c45a120f73d32 Mon Sep 17 00:00:00 2001 From: bsncubed Date: Thu, 30 Jul 2026 20:22:30 +1000 Subject: [PATCH] docs: add a proper Windows build section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Windows previously got one line pointing vaguely at MSYS2, while every other platform got real commands — and the README's main instruction is `make build`, which stock Windows cannot run at all. Covers the three ways Windows actually differs: cgo needs a GCC-style compiler (MSVC will not do), there is no make, and a GUI build needs -H=windowsgui or Windows opens a console window behind the app on every launch. The Makefile does not pass that flag since it targets Unix, so the section gives the direct go build command and names the .exe output explicitly. Also notes that Windows, unlike Linux, needs no graphics dev packages because OpenGL ships with the OS. Co-Authored-By: Claude Opus 5 --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5a654fe..bf8e84c 100644 --- a/README.md +++ b/README.md @@ -89,8 +89,8 @@ sudo dnf install gcc libX11-devel libXcursor-devel libXrandr-devel \ sudo pacman -S gcc libx11 libxcursor libxrandr libxinerama mesa libxi ``` -On Windows, use a MinGW-w64 toolchain (for example via -[MSYS2](https://www.msys2.org/)) so cgo has a C compiler. +Windows needs a MinGW-w64 toolchain and has no `make` — it gets [its own +section below](#building-on-windows). On macOS the command line tools cover the C side entirely — there is no Homebrew formula to add for graphics. That makes it easy to run @@ -132,6 +132,77 @@ Without `make`, the equivalent is: go build -trimpath -ldflags "-s -w" -o bin/haul ./cmd/haul ``` +### Building on Windows + +Windows differs from the instructions above in three ways: cgo needs a +MinGW-w64 compiler, there is no `make`, and a GUI build needs an extra linker +flag to suppress the console window. All three are covered here. + +**1. Install Go.** Either + +```powershell +winget install GoLang.Go +``` + +or the `.msi` from [go.dev/dl](https://go.dev/dl/), which puts Go on `PATH` for +you. Open a **new** terminal afterwards, then check with `go version`. + +**2. Install a C compiler.** Go's cgo needs a GCC-style compiler — +**MSVC/`cl.exe` will not work.** [MSYS2](https://www.msys2.org/) is the usual +source: + +```powershell +winget install MSYS2.MSYS2 +``` + +Then open the **"MSYS2 UCRT64"** shell from the Start menu and install GCC: + +```sh +pacman -S mingw-w64-ucrt-x86_64-gcc +``` + +Add its `bin` directory to your Windows `PATH` so the normal Go toolchain can +find it — in PowerShell, as your user: + +```powershell +[Environment]::SetEnvironmentVariable("Path", + [Environment]::GetEnvironmentVariable("Path","User") + ";C:\msys64\ucrt64\bin", + "User") +``` + +Open a new terminal and confirm both are visible: + +```powershell +go version +gcc --version +``` + +**3. Build.** Windows has no `make`, so invoke the compiler directly from +PowerShell in the repo root: + +```powershell +go build -trimpath -ldflags "-s -w -H=windowsgui" -o bin\haul.exe .\cmd\haul +``` + +Then run `.\bin\haul.exe`. + +Two details in that command matter: + +- **`-H=windowsgui`** marks the binary as a GUI application. Without it Windows + opens a console window behind haul every time it launches. The Makefile does + not pass this, because it targets Unix — so on Windows prefer the command + above even if you do have `make`. +- **`-o bin\haul.exe`** names the output explicitly. Windows needs the `.exe` + extension to execute a file. + +If you would rather use the Makefile, install `make` inside the MSYS2 shell +(`pacman -S make`) and build from there — but you will still want to add +`-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. + ### Make targets | Target | Does |