Add Go binding with idiomatic generated API

Author: lijy91

.github/workflows/go-ci.yml

@@ -0,0 +1,100 @@
+name: Go CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "bindings/go/**"
+      - "core"
+      - "examples/go_*/**"
+      - "tools/codegen/**"
+      - "codegen"
+      - ".github/workflows/go-ci.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "bindings/go/**"
+      - "core"
+      - "examples/go_*/**"
+      - "tools/codegen/**"
+      - "codegen"
+      - ".github/workflows/go-ci.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test:
+    name: Build & Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Checkout core
+        run: git submodule update --init core
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22.x"
+          cache: false
+      - name: Install Linux dependencies
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y cmake pkg-config libgtk-3-dev libx11-dev libxi-dev xvfb
+      - uses: msys2/setup-msys2@v2
+        if: runner.os == 'Windows'
+        with:
+          msystem: UCRT64
+          install: mingw-w64-ucrt-x86_64-gcc
+      - name: Configure Windows cgo and DLL lookup
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          "C:\msys64\ucrt64\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          "$env:GITHUB_WORKSPACE\bindings\go\build" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          "CC=gcc" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+      - name: Build the native library
+        run: |
+          cmake -S bindings/go -B bindings/go/build -DCMAKE_BUILD_TYPE=Release
+          cmake --build bindings/go/build --config Release --parallel 4
+      - name: Check Go formatting
+        shell: bash
+        run: |
+          files=$(gofmt -l bindings/go/*.go examples/go_*/*.go)
+          if [ -n "$files" ]; then echo "$files"; exit 1; fi
+      - name: Vet
+        working-directory: bindings/go
+        run: go vet ./...
+      - name: Test
+        working-directory: bindings/go
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then xvfb-run -a go test -v ./...; else go test -v ./...; fi
+      - name: Build examples
+        shell: bash
+        run: |
+          for example in examples/go_*_example; do
+            (cd "$example" && go build -o "$RUNNER_TEMP/$(basename "$example").exe" .)
+          done
+
+  generated:
+    name: Check generated Go API
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: git submodule update --init core
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22.x"
+          cache: false
+      - uses: dtolnay/rust-toolchain@stable
+      - run: sudo apt-get update && sudo apt-get install -y libclang-dev
+      - run: cargo test --manifest-path tools/codegen/Cargo.toml -p codegen-bindings
+      - run: ./codegen check --lang go

AGENTS.md

@@ -1,6 +1,6 @@
 # libnativeapi workspace
 
-This is the workspace repo (`libnativeapi/nativeapi`, formerly `nativeapi-flutter` and `nativeapi-workspace`) for the [libnativeapi](https://github.com/libnativeapi) project family. Every binding (`bindings/dart/`, `bindings/rust/`, `bindings/csharp/`, `bindings/js/`, `bindings/python/`), the code generator (`tools/codegen/`), the `./codegen` script, the specs and the shared tooling live directly in this repo (the Rust and C# histories were merged in from `nativeapi-rust` and `nativeapi-csharp`); only `core/` and `bindings/dart/tray_manager/` are git submodules of independent repositories. Work inside a submodule is committed and pushed from that subdirectory; everything else is committed here.
+This is the workspace repo (`libnativeapi/nativeapi`, formerly `nativeapi-flutter` and `nativeapi-workspace`) for the [libnativeapi](https://github.com/libnativeapi) project family. Every binding (`bindings/dart/`, `bindings/rust/`, `bindings/csharp/`, `bindings/js/`, `bindings/python/`, `bindings/go/`), the code generator (`tools/codegen/`), the `./codegen` script, the specs and the shared tooling live directly in this repo (the Rust and C# histories were merged in from `nativeapi-rust` and `nativeapi-csharp`); only `core/` and `bindings/dart/tray_manager/` are git submodules of independent repositories. Work inside a submodule is committed and pushed from that subdirectory; everything else is committed here.
 
 ## Layout
 
@@ -11,8 +11,9 @@ bindings/
 ├── rust/           # the Rust binding: crates/{nativeapi,cnativeapi}
 ├── csharp/         # the C# binding: src/, tests/, NativeAPI.slnx
 ├── js/             # the JS/TS binding: a Node-API addon (src/) + TypeScript (lib/)
-└── python/         # the Python binding: ctypes package (nativeapi/) + native shim (src/)
-examples/           # every binding's example apps, prefixed dart_*, flutter_*, rust_*, csharp_*, js_*, python_*
+├── python/         # the Python binding: ctypes package (nativeapi/) + native shim (src/)
+└── go/             # the Go binding: generated cgo API + native shared library
+examples/           # every binding's example apps, prefixed dart_*, flutter_*, rust_*, csharp_*, js_*, python_*, go_*
 pubspec.yaml        # pub workspace + melos root: Dart packages and Flutter examples
 Cargo.toml          # cargo workspace root: Rust crates and examples
 tools/codegen/      # in-repo Rust workspace: the code generator
@@ -25,8 +26,8 @@ codegen             # Python entry point orchestrating the generators
 ## Architecture
 
 - `core` — the C++ core library (repo: `nativeapi-core`). The source of truth for the native API surface (windows, tray icons, menus, displays, keyboard, dialogs, storage, etc.) with per-platform implementations (macOS/Windows/Linux).
-- `tools/codegen` — three crates: `shared` (libclang parser, IR, naming), `capi` (C ABI + umbrella header), `bindings` (Rust/Dart/C#/JS/Python generators, consuming the IR JSON emitted by `capi`). Only `capi` depends on libclang. See tools/codegen/README.md.
-- `bindings/*` — language bindings wrapping the core library. All live in this repo and build against the `core/` submodule directly (Rust `build.rs`, the Dart `cnativeapi` package's build hook, the C# native CMake, the JS addon's and the Python binding's `CMakeLists.txt`). Only a published package carries its own copy of core, in `cxx_impl/`, which the release workflows vendor and never commit. The Rust binding layers `nativeapi` (safe API) over `cnativeapi` (FFI). The Python binding has no compiled extension: generated `ctypes` code (`nativeapi/_capi.py` plus one module per header) calls a shared library built from core and a small event loop shim, which `Application.run_async()` pumps from asyncio.
+- `tools/codegen` — three crates: `shared` (libclang parser, IR, naming), `capi` (C ABI + umbrella header), `bindings` (Rust/Dart/C#/JS/Python/Go generators, consuming the IR JSON emitted by `capi`). Only `capi` depends on libclang. See tools/codegen/README.md.
+- `bindings/*` — language bindings wrapping the core library. All live in this repo and build against the `core/` submodule directly (Rust `build.rs`, the Dart `cnativeapi` package's build hook, the C# native CMake, the JS, Python and Go bindings' `CMakeLists.txt`). Only a published package carries its own copy of core, in `cxx_impl/`, which the release workflows vendor and never commit. The Rust binding layers `nativeapi` (safe API) over `cnativeapi` (FFI). The Python binding has no compiled extension: generated `ctypes` code (`nativeapi/_capi.py` plus one module per header) calls a shared library built from core and a small event loop shim, which `Application.run_async()` pumps from asyncio.
 
 ## Design specs
 
@@ -50,13 +51,24 @@ breaks). When one is resolved, edit the spec text itself.
 Always drive the generators through `./codegen` at the workspace root:
 
 - `./codegen` — full run: C ABI, then all bindings
-- `./codegen capi` / `./codegen bindings [--lang rust,dart,csharp,js,python]`
+- `./codegen capi` / `./codegen bindings [--lang rust,dart,csharp,js,python,go]`
 - `./codegen check` — read-only verification, non-zero exit when stale (CI mode)
 - `./codegen readme` — copy the shared README sections (`tools/readme/*.md`, e.g. Contributing) into core and every binding; `check` flags drift, `sync` runs it. Edit the snippet, never the copies.
 - `./codegen sync [-m "msg"] [--push]` — full downstream propagation, see below
 
 Generated files start with `// AUTO-GENERATED. DO NOT EDIT.` (`#` in Python) — change the C++ headers in `core/src/` and regenerate instead of editing outputs. Files without that banner are hand-written and never overwritten. The header list (`API_HEADERS`) lives in `tools/codegen/shared/src/lib.rs`.
 
+Go builds require Go 1.22+, cgo and CMake 3.24+; build the shared library with
+`cmake -S bindings/go -B bindings/go/build && cmake --build bindings/go/build --config Release`.
+Go examples are standalone modules with a local `replace` pointing to `../../bindings/go`.
+The Go generator uses `gofmt` before writing and checking its output. Public Go getters
+omit `Get`, `ToString` becomes `String`, constructor names omit shared overload
+parameters, and fallible operations return `error` while predicates keep `bool`.
+Native singletons are exported values with methods (`DisplayManager.All()`,
+`Application.Run()`), backed by private stateless types.
+Object getters retain nil-for-absence semantics; native failures without detailed
+causes wrap `ErrOperationFailed`. Examples intentionally use dot imports as requested.
+
 ## Changing the core API
 
 A core change ripples to every binding. After editing headers in `core`, run:
@@ -95,8 +107,8 @@ scenarios for *this project's* examples live in [tools/gui/](tools/gui/README.md
 - `core` tracks `branch = main`. Use `make sync` to fast-forward it; `make status` to see dirty state everywhere; `make bump` to stage its pointer.
 - The leanflutter packages built on nativeapi (`tray_manager`, `window_manager`, `launch_at_startup`, …) live in their own repos under github.com/leanflutter and depend on the published `nativeapi`. Only `tray_manager` rides along, as the submodule `bindings/dart/tray_manager` (tracking `main`); it is not a member of the root pub workspace, melos ignores it, and CI does not check it out. To try one against local changes, point a `dependency_overrides` entry in that package at `bindings/dart/nativeapi_flutter` (and `nativeapi`, `cnativeapi`) and never commit the override.
 - Commit workspace submodule pointer updates only when the combination is compatible (a known-good snapshot).
-- Examples live in `examples/<binding>_<name>_example` (`dart_` for plain Dart programs, `flutter_`, `rust_`, `csharp_`, `js_`, `python_`), not inside the bindings; a new Dart, Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`, a JS one in the root `package.json`. A Python example is a standalone uv project whose `pyproject.toml` points `nativeapi` at `../../bindings/python` (`uv run main.py` builds the wheel). Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
-- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`, `js-ci.yml`, `python-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/dart_*` and `examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`, `examples/js_*`, `examples/python_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`), `python-v*` publishes the Python package to PyPI (`python-release.yml`: an sdist carrying core in `cxx_impl/`, and wheels built from it with cibuildwheel; the tag must equal `python-v` + the version in `bindings/python/pyproject.toml`); never push a bare `v*` tag for anything but the Dart packages. Nothing has been published to PyPI yet: the first release needs `nativeapi` set up on PyPI with this workflow and the `pypi` environment as a trusted publisher.
+- Examples live in `examples/<binding>_<name>_example` (`dart_` for plain Dart programs, `flutter_`, `rust_`, `csharp_`, `js_`, `python_`, `go_`), not inside the bindings; a new Dart, Flutter or Rust example must also be listed in the root `pubspec.yaml` / `Cargo.toml`, a C# one in `bindings/csharp/NativeAPI.slnx`, a JS one in the root `package.json`. A Python example is a standalone uv project whose `pyproject.toml` points `nativeapi` at `../../bindings/python` (`uv run main.py` builds the wheel). A Go example is a standalone module whose `go.mod` replaces `github.com/libnativeapi/nativeapi/bindings/go` with `../../bindings/go`. Only the pub.dev package examples (`bindings/dart/*/example`) stay inside their package.
+- CI is one workflow per binding (`dart-ci.yml`, `rust-ci.yml`, `csharp-ci.yml`, `js-ci.yml`, `python-ci.yml`, `go-ci.yml`), each running only for changes under its `bindings/<lang>/` and its examples (`examples/dart_*` and `examples/flutter_*` for Dart, `examples/rust_*`, `examples/csharp_*`, `examples/js_*`, `examples/python_*`, `examples/go_*`). Release tags are per binding: `v*` publishes the Dart packages (`dart-release.yml`), `rust-v*` publishes the crates (`rust-release.yml`), `python-v*` publishes the Python package to PyPI (`python-release.yml`: an sdist carrying core in `cxx_impl/`, and wheels built from it with cibuildwheel; the tag must equal `python-v` + the version in `bindings/python/pyproject.toml`); never push a bare `v*` tag for anything but the Dart packages. Nothing has been published to PyPI yet: the first release needs `nativeapi` set up on PyPI with this workflow and the `pypi` environment as a trusted publisher.
 - The Dart packages `cnativeapi`, `nativeapi` and `nativeapi_flutter` share one version: a release bumps all three pubspecs and CHANGELOGs, because pub.dev's automated publishing matches the tag `v<version>` against each package's own version. `cnativeapi` and `nativeapi` are plain Dart (no Flutter dependency; a build hook compiles core); `nativeapi_flutter` is the Flutter-facing package, holding the widgets, the `dart:ui` conversions and `windowing.dart`, and re-exporting `nativeapi` minus the names that clash with Flutter's.
 - Never commit in a submodule while on a detached HEAD — check out `main` first (`./codegen sync` enforces this).
 - Do not add Co-Authored-By trailers to commits.

README.md

@@ -1,14 +1,14 @@
 # nativeapi
 
-Unified access to native system APIs — windows, tray icons, menus, displays, keyboard, dialogs, storage and more — from Dart/Flutter, Rust, C#, JavaScript/TypeScript and Python, all built on one C++ core.
+Unified access to native system APIs — windows, tray icons, menus, displays, keyboard, dialogs, storage and more — from Dart/Flutter, Rust, C#, JavaScript/TypeScript, Python and Go, all built on one C++ core.
 
 | Android | iOS | Linux | macOS | Windows |
 |:-------:|:---:|:-----:|:-----:|:-------:|
 | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 🚧 **Work in Progress**: the API is under active development.
 
-This repository is the home of every binding: the Dart, Rust, C#, JS and Python bindings, the code generator, the design specs and the shared tooling live here directly, and the C++ core ([nativeapi-core](https://github.com/libnativeapi/nativeapi-core)) is checked out as a git submodule. A core change and its regenerated bindings (core → codegen → bindings) are made and tracked together.
+This repository is the home of every binding: the Dart, Rust, C#, JS, Python and Go bindings, the code generator, the design specs and the shared tooling live here directly, and the C++ core ([nativeapi-core](https://github.com/libnativeapi/nativeapi-core)) is checked out as a git submodule. A core change and its regenerated bindings (core → codegen → bindings) are made and tracked together.
 
 ## Bindings
 
@@ -19,6 +19,7 @@ This repository is the home of every binding: the Dart, Rust, C#, JS and Python
 | [C#](bindings/csharp) | `NativeAPI` | not yet on NuGet; build from source |
 | [JavaScript / TypeScript](bindings/js) | `nativeapi` (Node-API addon for Node.js, Deno and Bun) | not yet on npm |
 | [Python](bindings/python) | `nativeapi` (`ctypes`, Python 3.10+) | prototype, not yet on PyPI |
+| [Go](bindings/go) | `github.com/libnativeapi/nativeapi/bindings/go` (cgo, Go 1.22+) | build from source |
 
 Each binding's README covers installation and usage.
 
@@ -36,7 +37,8 @@ This repository was `nativeapi-flutter`, then `nativeapi-workspace`, and is now
 | [bindings/csharp](bindings/csharp) | C# binding |
 | [bindings/js](bindings/js) | JavaScript / TypeScript binding (Node-API addon) |
 | [bindings/python](bindings/python) | Python binding (`ctypes`) |
-| [examples](examples) | example apps of every binding, prefixed by binding: `flutter_*`, `rust_*`, `csharp_*`, `js_*`, `python_*`, … |
+| [bindings/go](bindings/go) | Go binding (cgo) |
+| [examples](examples) | example apps of every binding, prefixed by binding: `flutter_*`, `rust_*`, `csharp_*`, `js_*`, `python_*`, `go_*`, … |
 | [tools/codegen](tools/codegen) | the C ABI and binding generators |
 | [specs](specs) | design rules for the core's public API |
 
@@ -86,7 +88,7 @@ Work on the bindings, the tooling and the specs is committed here directly. Work
 
 ## Releases
 
-Each binding is released from a tag of its own: `v<version>` publishes the Dart packages to pub.dev (`dart-release.yml`), `rust-v<version>` publishes the crates to crates.io (`rust-release.yml`). The C#, JS and Python bindings are not published yet.
+Each binding is released from a tag of its own: `v<version>` publishes the Dart packages to pub.dev (`dart-release.yml`), `rust-v<version>` publishes the crates to crates.io (`rust-release.yml`). The C#, JS, Python and Go bindings are not published yet.
 
 ## License
 

bindings/go/.gitignore

@@ -0,0 +1 @@
+/build/

bindings/go/CMakeLists.txt

@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.24)
+project(nativeapi_go LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/../../core/src" nativeapi_core)
+
+# Whole-archive keeps every C ABI symbol, including APIs Go hasn't called yet.
+add_library(nativeapi_go SHARED src/runtime.cpp)
+target_link_libraries(nativeapi_go PRIVATE $<LINK_LIBRARY:WHOLE_ARCHIVE,nativeapi>)
+set_target_properties(nativeapi_go PROPERTIES
+  LINKER_LANGUAGE CXX
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+  ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+)
+# cgo uses one stable path for both single- and multi-configuration generators.
+foreach(config DEBUG RELEASE RELWITHDEBINFO MINSIZEREL)
+  set_target_properties(nativeapi_go PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY_${config} "${CMAKE_BINARY_DIR}"
+    RUNTIME_OUTPUT_DIRECTORY_${config} "${CMAKE_BINARY_DIR}"
+    ARCHIVE_OUTPUT_DIRECTORY_${config} "${CMAKE_BINARY_DIR}"
+  )
+endforeach()