From fcf8f91e140831dd57b8d59e48d76b8e63dc23ba Mon Sep 17 00:00:00 2001
From: Esteban Zimanyi <esteban.zimanyi@ulb.be>
Date: Wed, 22 Jul 2026 15:59:03 +0200
Subject: [PATCH] Document how to regenerate the binding by hand

The generation contract describes the policy and the inputs, but carries no
command, so running the chain outside CI means reconstructing it from the
workflow and the pom.

Give the steps: derive libmeos and the catalog from the MobilityDB commit being
targeted, build the JMEOS jar against that catalog and install it under the
coordinates this build resolves, stage the catalog, and build. State how the
tests locate libmeos.
---
 GENERATION.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/GENERATION.md b/GENERATION.md
index 684c7d4..226ece5 100644
--- a/GENERATION.md
+++ b/GENERATION.md
@@ -68,3 +68,45 @@ installed as `org.jmeos:meos:1.0`; the generator reads its raw-FFI surface. The
 the smoke tests load is built from the **same** master catalog, so the jar surface, the
 facades and the native library all track master together — surface-match by construction,
 with no committed jar or pinned commit to drift.
+
+## Regenerating by hand
+
+CI performs the steps below via `provision-meos`. To run them yourself you need a JDK, Maven,
+CMake and the MEOS build dependencies.
+
+**1. Derive libmeos and the catalog from MobilityDB master.** Both come from one commit; see
+`MEOS-API/GENERATION.md` for the two commands:
+
+```bash
+MDB=~/src/MobilityDB                     # checkout at the commit you are deriving from
+MEOSAPI=~/src/MEOS-API
+cmake -S "$MDB" -B "$MDB/build" -DCMAKE_BUILD_TYPE=Release -DMEOS=ON -DALL=ON
+cmake --build "$MDB/build" -j"$(nproc)"
+cmake --install "$MDB/build" --prefix "$MDB/.prefix"
+cd "$MEOSAPI" && MDB_SRC_ROOT="$MDB" python3 run.py "$MDB/.prefix/include"
+```
+
+**2. Build the JMEOS jar against that catalog and install it into the local Maven
+repository** under the coordinates this build resolves — `org.jmeos:meos:1.0`:
+
+```bash
+cd ~/src/JMEOS                            # JMEOS main
+CATALOG="$MEOSAPI/output/meos-idl.json" LIBMEOS="$MDB/.prefix/lib/libmeos.so" \
+  tools/regen-from-catalog.sh
+mvn install:install-file -Dfile=jar/JMEOS.jar \
+  -DgroupId=org.jmeos -DartifactId=meos -Dversion=1.0 -Dpackaging=jar
+```
+
+**3. Stage the catalog and build.** `tools/meos-idl.json` is derived, not committed:
+
+```bash
+cd ~/src/MobilityFlink
+cp "$MEOSAPI/output/meos-idl.json" tools/meos-idl.json
+cd flink-processor
+mvn -Dmeos.lib.dir="$MDB/.prefix/lib" -Dmeos.enabled=true clean test
+```
+
+`generate-sources` runs `tools/codegen_jvm.py --engine flink --catalog ../tools/meos-idl.json
+--jar <the installed jar> --out target/generated-facades`, so the `MeosOps*` facades are
+regenerated by the build itself. `meos.lib.dir` is where the smoke tests look for
+`libmeos.so`, and `meos.enabled` turns them on.