From af882c61ef12a4c9658bf07dbe0226963d5546f5 Mon Sep 17 00:00:00 2001 From: Turtle Dove Date: Sun, 19 Jul 2026 23:32:58 -0500 Subject: [PATCH] docs: Improve Go bindings instructions with real-world setup guidance - Complete rewrite of bindings/go/README.md: - Prerequisites table per-OS (Windows/Linux/macOS) - Windows MinGW-w64 setup (the #1 failure point) - LLVM clang -mthreads error documented with fix - CGO_ENABLED=0 pitfall explained - 'Using in your own project' section with replace directive - Troubleshooting table (6 common errors with fixes) - Toolchain verification commands - Main README Quick Start updated with same guidance - All guidance validated against actual build attempts on Windows --- README.md | 15 ++++- bindings/go/README.md | 144 ++++++++++++++++++++++++++++++++++++------ 2 files changed, 138 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 5ab2b5216..0b729599f 100644 --- a/README.md +++ b/README.md @@ -85,19 +85,30 @@ This fork tracks upstream and contributes back via PRs: ## Go Bindings -This fork includes Go (cgo) bindings for Dear ImGui: +This fork includes Go (cgo) bindings for Dear ImGui — see **[bindings/go/README.md](bindings/go/README.md)** for full setup instructions (including the Windows MinGW gotchas). ``` bindings/go/ imgui_bridge.h/.cpp — Thin C API bridge (extern "C") imgui.go — Go cgo wrapper package - README.md — Full documentation + README.md — Full documentation + troubleshooting examples/example_golang/ main.go — Null-mode example Makefile — Build targets ``` +**Quick start:** +```bash +# Requires: Go 1.21+, C++ compiler (MinGW-w64 gcc on Windows), CGO_ENABLED=1 +cd examples/example_golang +go mod tidy +CGO_ENABLED=1 go build -o imgui_go_example . +./imgui_go_example +``` + +> **Windows users:** Go's cgo needs **MinGW-w64 gcc** (install via MSYS2: `pacman -S mingw-w64-x86_64-gcc`). LLVM clang fails with `-mthreads` errors. Verify with `go env CC CXX CGO_ENABLED`. + ## Sync Status | Branch | Tracks | Status | diff --git a/bindings/go/README.md b/bindings/go/README.md index d02eff418..b51dcc7aa 100644 --- a/bindings/go/README.md +++ b/bindings/go/README.md @@ -11,14 +11,108 @@ imgui_bridge.cpp → C API implementation (wraps C++ ImGui) go.mod → Go module definition ``` -The Go package calls C functions via cgo, which in turn call the C++ ImGui API through the bridge layer. +The Go package calls C functions via cgo, which calls the C++ ImGui API through the bridge. + +--- ## Prerequisites -- **Go 1.21+** (with `CGO_ENABLED=1`) -- **C++ compiler** (g++ or clang++) on PATH +| Requirement | Windows | Linux | macOS | +|---|---|---|---| +| **Go** | 1.21+ | 1.21+ | 1.21+ | +| **C++ compiler** | MinGW-w64 gcc/g++ | g++ | clang++ (Xcode CLT) | +| **CGO** | `CGO_ENABLED=1` | enabled by default | enabled by default | -## Usage +> **⚠️ Most common failure:** `CGO_ENABLED=0` because Go can't find a C compiler. +> Check with `go env CC CXX CGO_ENABLED`. If `CGO_ENABLED=0`, cgo is disabled and the build will fail with "build constraints exclude all Go files". + +### Windows Setup (the tricky one) + +Go's cgo on Windows requires a **gcc-compatible** compiler. The default `CC=gcc`, `CXX=g++`. + +**Option A — MinGW-w64 (recommended):** +```bash +# Install via MSYS2: https://www.msys2.org/ +pacman -S mingw-w64-x86_64-gcc +# Add to PATH: C:\msys64\mingw64\bin + +# Verify +gcc --version +g++ --version +go env CC CXX CGO_ENABLED # should show CGO_ENABLED=1 +``` + +**Option B — TDM-GCC:** +Download from https://jmeubank.github.io/tdm-gcc/ and add `bin` to PATH. + +**⚠️ LLVM/Clang on Windows does NOT work out of the box:** +`clang++` targeting `x86_64-pc-windows-msvc` fails with `unsupported option '-mthreads'`. +If you must use clang, you need a MinGW-targeted clang build and: +```bash +set CC=clang +set CXX=clang++ +set CGO_CFLAGS=-D__USE_MINGW_ANSI_STDIO +``` +(MinGW-w64 gcc is far easier.) + +### Linux Setup +```bash +sudo apt install build-essential golang # Debian/Ubuntu +sudo dnf install gcc-c++ golang # Fedora +``` + +### macOS Setup +```bash +xcode-select --install # provides clang/clang++ +brew install go +``` + +--- + +## Building the Example + +```bash +# Clone the repo +git clone https://github.com/Turtle-PB/imgui_xl.git +cd imgui_xl/examples/example_golang + +# Download module deps (uses a local `replace` directive to ../../bindings/go) +go mod tidy + +# Build +# Linux/macOS: +CGO_ENABLED=1 go build -o imgui_go_example . + +# Windows (MinGW on PATH): +set CGO_ENABLED=1 +go build -o imgui_go_example.exe . + +# Run +./imgui_go_example # Linux/macOS +imgui_go_example.exe # Windows +``` + +Or use the provided Makefile (Linux/macOS/MinGW): +```bash +cd examples/example_golang +make build # compile +make run # compile + run +make clean # remove artifacts +``` + +--- + +## Using the Bindings in Your Own Project + +The bindings module lives inside this repo, so use a `replace` directive: + +```bash +# In your project directory +go mod init myapp +go mod edit -require=github.com/Turtle-PB/imgui_xl/bindings/go@v0.0.0 +go mod edit -replace=github.com/Turtle-PB/imgui_xl/bindings/go=/path/to/imgui_xl/bindings/go +go mod tidy +``` ```go package main @@ -31,12 +125,11 @@ import ( func main() { imgui.CreateContext() defer imgui.DestroyContext() - + imgui.StyleColorsDark() - + imgui.NewFrame() - visible := imgui.Begin("Hello, Go!", nil) - if visible { + if imgui.Begin("Hello, Go!", nil) { imgui.Text("Hello from Go!") imgui.Text(fmt.Sprintf("FPS: %.1f", imgui.GetFramerate())) } @@ -45,20 +138,33 @@ func main() { } ``` -## Building +> **Note:** This example runs in "null" mode (no window). For a real window, +> pair with a Go windowing library (GLFW, SDL2) and a renderer backend. +> The cgo wrapper calls into the same C++ backends in `backends/`. +--- + +## Troubleshooting + +| Error | Cause | Fix | +|---|---|---| +| `build constraints exclude all Go files` | `CGO_ENABLED=0` | Set `CGO_ENABLED=1` and install a C compiler | +| `gcc: command not found` / `g++: command not found` | No C++ compiler on PATH | Install MinGW-w64 (Windows) or build-essential (Linux) | +| `unsupported option '-mthreads'` (Windows) | Using LLVM clang targeting MSVC | Use MinGW-w64 gcc instead | +| `undefined reference to 'ig_*'` | Bridge .cpp not compiled | Ensure `imgui_bridge.cpp` is in the same dir as `imgui.go` (it is, in this repo) | +| `cannot find -lstdc++` | Missing C++ stdlib | Install g++ (not just gcc) | +| cgo flag errors mentioning `-std=c++11` | Compiler too old | Use GCC 5+ / Clang 3.4+ | + +### Verify your toolchain before building: ```bash -# Set up the Go module (from the example directory) -cd examples/example_golang -go mod tidy - -# Build (requires C++ compiler) -CGO_ENABLED=1 go build -o imgui_go_example - -# Run -./imgui_go_example +go env CC CXX CGO_ENABLED +# Expected (Windows MinGW): CC=gcc CXX=g++ CGO_ENABLED=1 +# Expected (Linux): CC=gcc CXX=g++ CGO_ENABLED=1 +# Expected (macOS): CC=clang CXX=clang++ CGO_ENABLED=1 ``` +--- + ## Available Functions ### Core @@ -87,4 +193,4 @@ CGO_ENABLED=1 go build -o imgui_go_example ## License -MIT — same as Dear ImGui +MIT — same as Dear ImGui. Copyright (c) 2024 OwlLogics / imgui_xl.