From 54f8dbffe7b4c2817f820e20177791334b1cd450 Mon Sep 17 00:00:00 2001
From: bsncubed <ben@apointless.space>
Date: Thu, 30 Jul 2026 00:00:50 +1000
Subject: [PATCH] docs: make the Go toolchain an explicit prerequisite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Building needs both Go and a C toolchain, but only the C toolchain had install
commands — so the macOS path read as though `xcode-select --install` was the
whole job. Running it and being told the tools are already present looks like
success right up until `make build` fails with `go: command not found`.

Splits Prerequisites into two numbered steps with install commands for each,
`brew install go` on macOS, and says plainly that both are required.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md | 37 ++++++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 169cac0..5a654fe 100644
--- a/README.md
+++ b/README.md
@@ -48,11 +48,36 @@ the Go toolchain.
 
 ### Prerequisites
 
-**Go 1.24 or newer** — check with `go version`.
+There are **two** prerequisites — the Go toolchain, and a C toolchain for cgo.
+Both are needed on every platform, macOS included.
 
-Then the C toolchain and system headers Fyne needs:
+**1. Go 1.24 or newer.** Verify with `go version`; if that says
+`command not found`, install it:
 
 ```sh
+# macOS
+brew install go
+
+# Debian / Ubuntu
+sudo apt install golang-go
+
+# Fedora
+sudo dnf install golang
+
+# Arch
+sudo pacman -S go
+```
+
+Or download it from [go.dev/dl](https://go.dev/dl/). If your distro's package
+is older than 1.24, use the tarball from there instead.
+
+**2. A C toolchain and the platform's graphics headers**, because Fyne renders
+through OpenGL:
+
+```sh
+# macOS — the Xcode command line tools
+xcode-select --install
+
 # Debian / Ubuntu
 sudo apt install gcc libgl1-mesa-dev xorg-dev
 
@@ -62,14 +87,16 @@ sudo dnf install gcc libX11-devel libXcursor-devel libXrandr-devel \
 
 # Arch
 sudo pacman -S gcc libx11 libxcursor libxrandr libxinerama mesa libxi
-
-# macOS — the Xcode command line tools
-xcode-select --install
 ```
 
 On Windows, use a MinGW-w64 toolchain (for example via
 [MSYS2](https://www.msys2.org/)) so cgo has a C compiler.
 
+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
+`xcode-select --install`, see "already installed", and assume you're ready when
+Go itself is still missing. Both steps are required.
+
 ### Build it
 
 ```sh