Generate the GoMEOS flat FFI layer from the MEOS-API catalog

.github/workflows/build.yml

@@ -0,0 +1,76 @@
+name: build
+
+# Derive the MEOS catalog and the all-families libmeos from a single
+# MobilityDB commit via the shared provision-meos action (the same derivation
+# JMEOS / Spark / PyMEOS-CFFI consume), regenerate the flat FFI functions
+# package from that catalog, and prove the committed generated code is in sync
+# with it. No MEOS header is parsed in this repository: the functions package
+# is a projection of the catalog, and cgo only compiles it against the
+# installed libmeos. The catalog itself is never committed — it is derived
+# here from MobilityDB.
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Provision catalog + build GoMEOS (Linux, all families)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Provision MEOS (catalog + all-families libmeos)
+        id: provision
+        uses: MobilityDB/MEOS-API/.github/actions/provision-meos@master
+        with:
+          mobilitydb-ref: master
+          build-libmeos: "true"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Stage the derived catalog for the generator
+        run: cp "${{ steps.provision.outputs.catalog-path }}" tools/meos-idl.json
+
+      - name: Regenerate the functions package from the catalog
+        run: python3 tools/codegen.py
+
+      - name: Report drift between the committed and freshly derived functions package
+        run: |
+          # Informational only: CI builds and tests the FRESHLY regenerated
+          # functions/ above, so a drift against the committed snapshot never
+          # fails the build (MobilityDB master moves independently of this repo).
+          # The committed functions/ is a convenience snapshot for `go get`
+          # consumers; refresh it by running 'python3 tools/codegen.py' against a
+          # freshly derived meos-idl.json and committing the result.
+          if ! git diff --quiet -- functions/; then
+            echo "::notice::functions/ differs from the freshly derived catalog (snapshot lags MobilityDB master):"
+            git diff --stat -- functions/
+          else
+            echo "functions/ snapshot is in sync with the derived catalog."
+          fi
+
+      - name: Build the generated functions package against the all-families libmeos
+        env:
+          CGO_CFLAGS: -I/usr/local/include -I/usr/include/h3
+          CGO_LDFLAGS: -L/usr/local/lib -lmeos
+          LD_LIBRARY_PATH: /usr/local/lib
+        run: go build ./functions
+
+      - name: Run the portable-parity gate
+        env:
+          CGO_ENABLED: "0"
+        run: go test ./tools/parity/

.github/workflows/portable-parity.yml

@@ -0,0 +1,40 @@
+name: portable-aliases parity
+
+# Gates the portable bare-name dialect (RFC #920; MEOS-API cross-repo
+# handoff PR #9): GoMEOS's exposed CGO symbol set — the hand-written root
+# package plus the IDL-driven generated surface (tools/_preview, emitted
+# by tools/codegen.py from tools/meos-idl.json, the MEOS-API parser's
+# JSON output) — must remain a superset of portableAliases.bareNames:
+# 29/29, 0 unbacked, and every one of the six in-scope user-facing type
+# families (temporal, geo, cbuffer, npoint, pose, rgeo) covered.
+# cbuffer/npoint/pose/rgeo are full temporal types and are never excluded
+# from the parity headline.
+#
+# Neither job needs libmeos/CGO: both audit the source statically, so the
+# gate is self-contained and cannot be flaked by the C toolchain.
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  parity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Parity gate (script — exposed symbol set ⊇ bareNames)
+        run: python3 tools/portable_parity.py --check
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Parity gate (Go test — language-independent mirror)
+        env:
+          CGO_ENABLED: '0'
+        run: go test ./tools/parity/ -v

.gitignore

@@ -1,2 +1,6 @@
 cgo_flag_config.go
-/test
+/test
+# Derived MEOS catalog: generated in CI from MobilityDB via the shared
+# provision-meos action (MEOS-API run.py), never committed. The flat FFI
+# functions package is projected from it and IS committed.
+tools/meos-idl.json

README.md

@@ -1,12 +1,14 @@
 # GoMEOS
 
 [MEOS (Mobility Engine, Open Source)](https://www.libmeos.org/) is a C library which enables the manipulation of
-temporal and spatio-temporal data based on [MobilityDB](https://mobilitydb.com/)'s data types and functions.
+temporal and spatio-temporal data based on [MobilityDB](https://github.com/MobilityDB/MobilityDB)'s data types and functions.
 
-GoMEOS is a Go library that wraps the MEOS C library using [CGO](https://pkg.go.dev/cmd/cgo), providing a set of Go functions that allows to use MEOS functionality by directly accessing C structs and C functions.
+GoMEOS is a Go library that wraps the MEOS C library using [CGO](https://pkg.go.dev/cmd/cgo), providing a set of Go functions that allows to use MEOS functionality by directly accessing C structs and C functions. It tracks MEOS 1.4.
 
 GoMEOS exposes the functionality of MEOS and is meant to be used directly by the user.
 
+The wrappers are generated from the [MEOS-API](https://github.com/MobilityDB/MEOS-API) `meos-idl.json` catalog rather than written by hand. To regenerate them against a given MEOS version, see [`tools/README.md`](tools/README.md).
+
 # Usage
 
 ## Installation

cast.h

@@ -17,7 +17,9 @@
 #define gunion_spanset_spanset union_spanset_spanset
 
 
+#include <stddef.h>
 #include "meos.h"
+#include "meos_geo.h"
 #include <stdio.h>
 #include <stdlib.h>
 

functions/cgo.go

@@ -0,0 +1,32 @@
+package functions
+
+/*
+// Every optional MEOS family is enabled so the ``#if <FAMILY>``-guarded
+// declarations in the core headers (e.g. meos_initialize_pointcloud) are
+// visible -- matching the all-families libmeos the catalog is derived from, in
+// sync with MobilityDB CMakeLists.txt's ``if(ALL)`` loop (alphabetical). The
+// families expose external library types (H3's h3api.h) through their own
+// headers, so their include dirs are added too.
+#cgo darwin CFLAGS: -I/opt/homebrew/include -I/opt/homebrew/include/h3 -DMEOS=1 -DARROW=1 -DCBUFFER=1 -DH3=1 -DJSON=1 -DNPOINT=1 -DPOINTCLOUD=1 -DPOSE=1 -DQUADBIN=1 -DRASTER=1 -DRGEO=1
+#cgo darwin LDFLAGS: -L/opt/homebrew/lib -lmeos -Wl,-rpath,/opt/homebrew/lib
+
+#cgo linux CFLAGS: -I/usr/local/include/ -I/usr/include/h3 -DMEOS=1 -DARROW=1 -DCBUFFER=1 -DH3=1 -DJSON=1 -DNPOINT=1 -DPOINTCLOUD=1 -DPOSE=1 -DQUADBIN=1 -DRASTER=1 -DRGEO=1
+#cgo linux LDFLAGS: -L/usr/local/lib -lmeos -Wl,-rpath,/usr/local/lib
+
+#include <stddef.h>
+#include "meos.h"
+#include "meos_catalog.h"
+#include "meos_geo.h"
+#include "meos_internal.h"
+#include "meos_internal_geo.h"
+#include "meos_npoint.h"
+#include "meos_cbuffer.h"
+#include "meos_pose.h"
+#include "meos_rgeo.h"
+#include "meos_h3.h"
+#include "meos_quadbin.h"
+#include "meos_json.h"
+#include "meos_pointcloud.h"
+#include "meos_arrow.h"
+*/
+import "C"