docs: add a proper Windows build section

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 <noreply@anthropic.com>
This commit is contained in:
2026-07-30 20:22:30 +10:00
parent 0d938f1f64
commit 47ad62bb84
+73 -2
View File
@@ -89,8 +89,8 @@ sudo dnf install gcc libX11-devel libXcursor-devel libXrandr-devel \
sudo pacman -S gcc libx11 libxcursor libxrandr libxinerama mesa libxi sudo pacman -S gcc libx11 libxcursor libxrandr libxinerama mesa libxi
``` ```
On Windows, use a MinGW-w64 toolchain (for example via Windows needs a MinGW-w64 toolchain and has no `make` — it gets [its own
[MSYS2](https://www.msys2.org/)) so cgo has a C compiler. section below](#building-on-windows).
On macOS the command line tools cover the C side entirely — there is no 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 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 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 ### Make targets
| Target | Does | | Target | Does |