Skip to content

GENERATION.md

Latest commit

 

History

History
57 lines (44 loc) · 3.13 KB

GENERATION.md

File metadata and controls

57 lines (44 loc) · 3.13 KB
Raw

JMEOS generation — the canonical per-binding generator policy

JMEOS is a generated binding. This document is the contract for how it is generated, under the ecosystem-wide per-binding generator policy.

The policy (ecosystem-wide)

Every MobilityDB language binding is a pure projection of the MEOS-API catalog, and each binding owns its own generator, in its own repo, in a canonical layout — not a single central generator-repo. The single source of truth is the catalog (MEOS-API/output/meos-idl.json, generated from the MEOS C headers), not a generator location. This mirrors how MEOS itself is built: independent, plug-and-play, CMake-gated families — a binding is likewise an independent module that owns its generation.

Each binding repo satisfies the same invariants:

  1. In-repo generator, one clearly-designated location. For JMEOS that is the codegen/ Maven module (codegen/src/main/java/FunctionsGenerator.java).
  2. Own pin manifest tools/pin/compose-order.txt — the canonical, dependency-ordered fold list of the open PRs that compose this binding's 1.4 surface onto main.
  3. Vendored catalog, version-pinned, read-only: codegen/input/meos-idl.json.
  4. Thin language projection — language-neutral decisions (grouping, skip/classify, portable names, shape) belong upstream in the catalog, so per-language generators do not re-implement and drift.
  5. Full automation (North Star): generate-then-retire toward a zero hand-written surface; anything that seems irreducible is either emitted by the generator or fixed at source in MEOS (export the symbol) — never hand-patched in the binding.

JMEOS scope: raw FFI ONLY

JMEOS owns the raw FFI projection: FunctionsGenerator.java → jmeos-core/.../functions/GeneratedFunctions.java plus the OO type layer.

The org.mobilitydb.meos.MeosOps* facades and the Spark-Connect registrar are consumer projections — they are generated in their consumer bindings (MobilityFlink / MobilityKafka / MobilitySpark), not in JMEOS. Flink already carries the facade generator (tools/codegen_facades.py). Keeping them out of JMEOS is what prevents the FFI line and the facade line from diverging again.

Generate-then-retire — the green-CI version is the probe

Removing hand-written code happens little by little, never wipe-first:

  1. build/align the generator to the canonical structure;
  2. generate the full surface, build green;
  3. prove generated ⊇ hand against the last green-CI version (the equivalence probe) — suite + parity, family by family;
  4. retire the hand registrations for that family;
  5. repeat. The green-CI baseline is what catches a generated gap before it ships.

Pinning: this binding's catalog comes from a MobilityDB pin

JMEOS's vendored codegen/input/meos-idl.json is generated from a MobilityDB ecosystem-pin-* (master ⊕ the MobilityDB compose-order). That pin is the catalog/surface input; JMEOS's own tools/pin/compose-order.txt governs this repo's PR accumulate. See tools/pin/compose-order.txt for the current composing set and the disposition of every open PR.