From 01a160bf6634b3a9b3e1c7fb6950f248e6c0821d 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 | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/GENERATION.md b/GENERATION.md
index 27d5188..f959937 100644
--- a/GENERATION.md
+++ b/GENERATION.md
@@ -34,3 +34,43 @@ Tracking master keeps the source and the `@master` derivation toolchain moving t
 so the catalog and jar never drift from the `run.py` that derives them.
 
 The UDF layer is the generated `registerAll()` — zero hand-written registrations.
+
+## 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/MobilitySpark
+cp "$MEOSAPI/output/meos-idl.json" tools/meos-idl.json
+LD_LIBRARY_PATH="$MDB/.prefix/lib" mvn clean test
+```
+
+`generate-sources` runs `tools/codegen_jvm.py --engine spark --catalog tools/meos-idl.json
+--jar <the installed jar> --out target/generated-sources/spark/...`, so the UDF layer is
+regenerated by the build itself. `LD_LIBRARY_PATH` is how the tests find `libmeos.so`.