From 9ad65a75b9a23cd8a27ec79159547957d2db770e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 23:57:15 -0500 Subject: [PATCH] docs: add a full "Building on Linux" section to the README Replaces the two-line Linux build note with a step-by-step guide: - compiler and graphics header packages for Debian/Ubuntu (same as CI), Fedora and Arch - installing Go, including how Go 1.21+ fetches the go.mod version itself - building, version stamping, running, and where settings/downloads go - optional: CI checks, release-style packaging, a .desktop menu entry - a note on building inside WSL - a troubleshooting table for common cgo/header/OpenGL errors Also updates the package list in build.sh's header comment to include the Wayland headers GLFW 3.4 needs, matching the CI workflow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D2Ppju4rH8FQpuXyDyWfaa --- README.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++- build.sh | 4 +- 2 files changed, 167 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 038139a..fa52196 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,7 @@ That's the whole philosophy: a powerful, secure tool, made simple enough for any - [Self-hosting a croc relay](#self-hosting-a-croc-relay) - [Troubleshooting](#troubleshooting) - [Building from source](#building-from-source) + - [Building on Linux](#building-on-linux) - [Developer CLI](#developer-cli) - [Project layout](#project-layout) - [How the croc integration works](#how-the-croc-integration-works) @@ -745,13 +746,173 @@ This produces `dist\TroopersTransfer.exe`. The script: a post-link patch because linking a `.syso` clashes with the default manifest MinGW adds. -### Linux +### Building on Linux + +You need three things: a C compiler and graphics headers (Fyne draws the +window with OpenGL through cgo), Go, and this repo. Ubuntu is the tested +path, because the [CI](#continuous-integration-and-releases) builds every +commit on `ubuntu-latest`. Other distros should work the same way once the +right packages are installed. + +**1. Install the compiler and graphics headers** + +Debian, Ubuntu, Linux Mint, Pop!_OS and WSL (Ubuntu). These are the same +packages the CI installs: ```bash -sudo apt-get install gcc libgl1-mesa-dev xorg-dev libxkbcommon-dev libwayland-dev -./build.sh # -> dist/TroopersTransfer +sudo apt-get update +sudo apt-get install -y git gcc libgl1-mesa-dev xorg-dev libxkbcommon-dev libwayland-dev +``` + +Fedora: + +```bash +sudo dnf install git gcc mesa-libGL-devel libX11-devel libXcursor-devel libXrandr-devel \ + libXinerama-devel libXi-devel libXxf86vm-devel libxkbcommon-devel wayland-devel +``` + +Arch, Manjaro and EndeavourOS: + +```bash +sudo pacman -S --needed git base-devel mesa libx11 libxcursor libxrandr \ + libxinerama libxi libxxf86vm libxkbcommon wayland +``` + +The Fedora and Arch lists aren't checked by CI. If one of them misses a +package, the build stops with a missing `.h` file. See +[Linux build problems](#linux-build-problems) below. + +**2. Get the code** + +```bash +git clone https://github.com/Trooper-code/TroopersTransfer.git +cd TroopersTransfer +``` + +**3. Install Go** + +The project needs the Go version listed in [`go.mod`](go.mod). Distro +packages are often older than that, but that's usually fine: **any Go from +1.21 on downloads the right version by itself** the first time you build. +You'll see a line like `go: downloading go1.27.1` and then the build carries +on. + +So the easiest route is your distro's package (`sudo apt-get install golang-go`, +`sudo dnf install golang` or `sudo pacman -S go`), then check it works: + +```bash +go version +``` + +If your distro's Go is older than 1.21, or you'd rather install the exact +version, get the official build from [go.dev/dl](https://go.dev/dl/). Run +this from inside the repo folder, so it picks the version from `go.mod`: + +```bash +GOVER=$(awk '/^go /{print $2}' go.mod) +curl -LO "https://go.dev/dl/go${GOVER}.linux-amd64.tar.gz" +sudo rm -rf /usr/local/go +sudo tar -C /usr/local -xzf "go${GOVER}.linux-amd64.tar.gz" +echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile +. ~/.profile +go version +``` + +On an ARM64 machine (for example a Raspberry Pi 5), use +`linux-arm64.tar.gz` instead of `linux-amd64.tar.gz`. + +**4. Build** + +```bash +./build.sh ``` +The first build takes a few minutes because it compiles the C graphics code; +later builds take seconds. When it's done, it prints the size of +`dist/TroopersTransfer`, which is the whole app. + +To stamp a version number into the **About** line and the updater, set +`VERSION`: + +```bash +VERSION=1.2.0 ./build.sh +``` + +**5. Run it** + +```bash +./dist/TroopersTransfer +``` + +It behaves exactly like the Windows build. It saves its settings in +`TroopersTransfer.json` next to the binary, or in +`~/.config/TroopersTransfer/` if that folder isn't writable. Received files +go to `~/Downloads/Troopers Transfer` (or your desktop's own Downloads +folder, if it's set to somewhere else). + +You can copy the `TroopersTransfer` file anywhere, such as a USB stick or +another PC with the same kind of CPU. The other PC doesn't need Go or any +of the packages above, just a normal desktop with working graphics. + +**Optional extras** + +Run the same checks as CI before opening a pull request: + +```bash +go vet ./... +go test ./... +``` + +Package it the same way the release does: + +```bash +tar -C dist -czf TroopersTransfer-linux-amd64.tar.gz TroopersTransfer +sha256sum TroopersTransfer-linux-amd64.tar.gz > TroopersTransfer-linux-amd64.tar.gz.sha256 +``` + +Add it to your desktop's app menu. Run this from the repo folder after +building: + +```bash +mkdir -p ~/.local/bin ~/.local/share/applications ~/.local/share/icons +cp dist/TroopersTransfer ~/.local/bin/ +cp assets/icon.png ~/.local/share/icons/troopers-transfer.png +cat > ~/.local/share/applications/troopers-transfer.desktop <= … (running go …; GOTOOLCHAIN=local)` | Your Go is too old and automatic downloads are switched off. | Run `export GOTOOLCHAIN=auto` and build again, or install the newer Go from step 3. | +| `go: downloading go…` then a network error | Go couldn't download the version it needs. | Check your internet connection, or install the exact version by hand (step 3). | +| `build constraints exclude all Go files` mentioning `glfw` or `gl` | cgo is switched off (`CGO_ENABLED=0`). | Use `./build.sh`, which switches it on, or run `export CGO_ENABLED=1`. | +| `./build.sh: Permission denied` | The script lost its "executable" flag, for example after copying it from a Windows drive. | Run `sh build.sh` instead, or `chmod +x build.sh` once. | +| It builds, but the window doesn't open: `APIUnavailable`, `GLX: No GLX visuals` or `failed to initialise OpenGL` | There's no working OpenGL. This usually happens in a virtual machine, over SSH, or on a server with no desktop. | Run it on a desktop session. In a VM, switch on 3D acceleration. As a last resort, `LIBGL_ALWAYS_SOFTWARE=1 ./dist/TroopersTransfer` uses software drawing (slower, but it works). | + ### macOS ```bash diff --git a/build.sh b/build.sh index 677c2ca..c674b14 100755 --- a/build.sh +++ b/build.sh @@ -1,6 +1,8 @@ #!/usr/bin/env sh # Builds TroopersTransfer for the current OS (Linux or macOS) into ./dist. -# Linux needs: gcc libgl1-mesa-dev xorg-dev (Debian/Ubuntu package names). +# Linux needs: gcc libgl1-mesa-dev xorg-dev libxkbcommon-dev libwayland-dev +# (Debian/Ubuntu package names; see "Building on Linux" in the README for +# Fedora and Arch). # macOS needs: Xcode command line tools. set -eu cd "$(dirname "$0")"