fix: arcadedb-embedded PyPI wheel will not install on manylinux_2_34_x86_64 (RHEL 9, Rocky 9, AlmaLinux 9, Amazon Linux 2023)

Fixed issue ArcadeData#4037

Author: lvca

bindings/python/scripts/Dockerfile.build

@@ -169,6 +169,7 @@ COPY bindings/python/setup.py .
 COPY bindings/python/scripts/setup_jars.py ./scripts/
 COPY bindings/python/scripts/extract_version.py ./scripts/
 COPY bindings/python/scripts/write_version.py ./scripts/
+COPY bindings/python/scripts/verify_wheel_platform_tag.py ./scripts/
 COPY bindings/python/scripts/jar_exclusions.txt .
 COPY bindings/python/pyproject.toml ./
 COPY bindings/python/README.md ./
@@ -195,7 +196,17 @@ RUN echo "📌 Package name: ${PACKAGE_NAME}" && \
     echo "📦 JAR files and JRE copied"
 
 # Build the wheel
-# Extract PEP 440 version from pom.xml or use BUILD_VERSION if provided
+# Extract PEP 440 version from pom.xml or use BUILD_VERSION if provided.
+#
+# Wheel platform tag must match the highest glibc symbol version required by the
+# bundled JRE. amazoncorretto:25 (Amazon Linux 2023, glibc 2.34) ships a JRE
+# whose binaries link against GLIBC_2.34 at most; older glibc symbol versions
+# cannot be back-ported. Issue #4037: tagging as manylinux_2_35 prevents
+# installation on systems with glibc 2.34 (RHEL 9, Rocky 9, AlmaLinux 9, Amazon
+# Linux 2023, ...) even though the bundled JRE runs there fine. Keep the tag
+# aligned with the JRE's actual requirement; bump only when the JRE base image
+# moves to a newer glibc. The verify_wheel_platform_tag.py step below enforces
+# this invariant at build time.
 ARG BUILD_VERSION=""
 RUN if [ -n "${BUILD_VERSION}" ]; then \
         export ARCADEDB_VERSION="${BUILD_VERSION}"; \
@@ -212,9 +223,9 @@ RUN if [ -n "${BUILD_VERSION}" ]; then \
     sed -i 's|^description = .*|description = "'"${PACKAGE_DESCRIPTION}"'"|' pyproject.toml && \
     if echo "${TARGET_PLATFORM}" | grep -q '^linux-'; then \
         if [ "${TARGET_PLATFORM}" = "linux-x64" ]; then \
-            WHEEL_PLAT="manylinux_2_35_x86_64"; \
+            WHEEL_PLAT="manylinux_2_34_x86_64"; \
         elif [ "${TARGET_PLATFORM}" = "linux-arm64" ]; then \
-            WHEEL_PLAT="manylinux_2_35_aarch64"; \
+            WHEEL_PLAT="manylinux_2_34_aarch64"; \
         else \
             WHEEL_PLAT=""; \
         fi; \
@@ -233,6 +244,10 @@ RUN if [ -n "${BUILD_VERSION}" ]; then \
             ls -lh /build/dist; \
             exit 1; \
         fi; \
+        WHEEL_FILE=$(ls /build/dist/*.whl | head -n1); \
+        if [ -n "${WHEEL_FILE}" ]; then \
+            python3 scripts/verify_wheel_platform_tag.py "${WHEEL_FILE}" /build/jre || exit 1; \
+        fi; \
     fi && \
     echo "✅ Wheel built successfully!" && \
     ls -lh dist/

bindings/python/scripts/verify_wheel_platform_tag.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Verify the Linux wheel's manylinux platform tag matches the bundled JRE.
+
+Regression guard for issue #4037: the wheel was tagged ``manylinux_2_35`` while
+the bundled JRE only required ``GLIBC_2.34``, blocking installation on systems
+running glibc 2.34 (RHEL 9, Rocky 9, AlmaLinux 9, Amazon Linux 2023, ...). The
+wheel platform tag must equal the highest ``GLIBC_x.y`` symbol version actually
+referenced by the JRE binaries (``java``, ``libjvm.so``, ...). Tagging higher
+locks out users unnecessarily; tagging lower lets the wheel install on systems
+where the JRE cannot run.
+
+Usage:
+    python verify_wheel_platform_tag.py <wheel_path> <jre_dir>
+        Verify a wheel's filename platform tag against the JRE in jre_dir.
+    python verify_wheel_platform_tag.py --jre <jre_dir>
+        Print the recommended manylinux tag for the JRE (no wheel check).
+
+Exits with status 0 on success, non-zero on mismatch.
+
+@author Luca Garulli (l.garulli@arcadedata.com)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+GLIBC_SYM_RE = re.compile(rb"GLIBC_(\d+)\.(\d+)(?:\.(\d+))?")
+WHEEL_TAG_RE = re.compile(r"-(manylinux_(\d+)_(\d+)_(x86_64|aarch64))\.whl$")
+
+
+def _max_glibc_in_file(path: Path) -> tuple[int, int] | None:
+    """Return the highest (major, minor) GLIBC_ symbol referenced by an ELF file."""
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    if not data.startswith(b"\x7fELF"):
+        return None
+    best: tuple[int, int] | None = None
+    for match in GLIBC_SYM_RE.finditer(data):
+        major = int(match.group(1))
+        minor = int(match.group(2))
+        if best is None or (major, minor) > best:
+            best = (major, minor)
+    return best
+
+
+def max_glibc_in_dir(jre_dir: Path) -> tuple[int, int]:
+    """Walk a JRE/JDK tree and return its highest GLIBC_ symbol version."""
+    best: tuple[int, int] = (0, 0)
+    found_any = False
+    for root, _dirs, files in os.walk(jre_dir):
+        for name in files:
+            p = Path(root) / name
+            if p.is_symlink():
+                continue
+            ver = _max_glibc_in_file(p)
+            if ver is None:
+                continue
+            found_any = True
+            if ver > best:
+                best = ver
+    if not found_any:
+        raise SystemExit(f"No ELF binaries with GLIBC_ symbols found under {jre_dir}")
+    return best
+
+
+def parse_wheel_tag(wheel_path: Path) -> tuple[tuple[int, int], str]:
+    """Extract (glibc_version, arch) from a manylinux wheel filename."""
+    match = WHEEL_TAG_RE.search(wheel_path.name)
+    if not match:
+        raise SystemExit(
+            f"Wheel '{wheel_path.name}' does not have a recognized manylinux_X_Y_arch tag"
+        )
+    return (int(match.group(2)), int(match.group(3))), match.group(4)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("wheel", nargs="?", type=Path, help="Path to the .whl file")
+    parser.add_argument("jre", nargs="?", type=Path, help="Path to the bundled JRE/JDK directory")
+    parser.add_argument("--jre", dest="jre_only", type=Path, help="Inspect a JRE only and print its required tag")
+    args = parser.parse_args()
+
+    if args.jre_only is not None:
+        major, minor = max_glibc_in_dir(args.jre_only)
+        print(f"manylinux_{major}_{minor}")
+        return 0
+
+    if args.wheel is None or args.jre is None:
+        parser.print_usage(sys.stderr)
+        return 2
+
+    wheel_glibc, _arch = parse_wheel_tag(args.wheel)
+    jre_glibc = max_glibc_in_dir(args.jre)
+
+    print(f"Wheel platform tag glibc: {wheel_glibc[0]}.{wheel_glibc[1]}")
+    print(f"JRE max GLIBC_ symbol:    {jre_glibc[0]}.{jre_glibc[1]}")
+
+    if wheel_glibc != jre_glibc:
+        print(
+            f"ERROR: wheel manylinux tag (manylinux_{wheel_glibc[0]}_{wheel_glibc[1]}) "
+            f"does not match the JRE's actual glibc requirement "
+            f"(manylinux_{jre_glibc[0]}_{jre_glibc[1]}). "
+            "Update WHEEL_PLAT in scripts/Dockerfile.build (issue #4037).",
+            file=sys.stderr,
+        )
+        return 1
+
+    print("OK: wheel platform tag matches the JRE's glibc requirement.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bindings/python/tests/test_wheel_platform_tag.py

@@ -0,0 +1,127 @@
+"""Regression tests for issue #4037: wheel manylinux platform tag.
+
+The Linux wheel must be tagged with the same glibc version that the bundled JRE
+binaries actually require. Tagging higher than the JRE needs (e.g. manylinux_2_35
+when the JRE only references GLIBC_2.34 symbols) blocks installation on systems
+running glibc 2.34 (RHEL 9, Rocky 9, AlmaLinux 9, Amazon Linux 2023, ...) for no
+reason. Tagging lower lets the wheel install where the JRE cannot run.
+
+These tests exercise the verifier script directly with synthetic ELF files so we
+do not depend on Docker or a built wheel.
+
+@author Luca Garulli (l.garulli@arcadedata.com)
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "verify_wheel_platform_tag.py"
+
+
+def _load_verifier():
+    spec = importlib.util.spec_from_file_location("verify_wheel_platform_tag", SCRIPT_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def _make_elf_with_glibc_symbols(path: Path, versions: list[str]) -> None:
+    """Create a tiny pseudo-ELF file containing GLIBC_X.Y strings.
+
+    The verifier only scans for the literal pattern ``GLIBC_<major>.<minor>``;
+    it does not parse ELF dynamic sections. A minimal ELF magic prefix plus the
+    embedded version strings is enough to mimic a real binary for the test.
+    """
+    payload = b"\x7fELF" + b"\x00" * 12
+    payload += b"\x00".join(f"GLIBC_{v}".encode("ascii") for v in versions)
+    payload += b"\x00"
+    path.write_bytes(payload)
+
+
+def test_max_glibc_in_dir_picks_highest(tmp_path: Path) -> None:
+    verifier = _load_verifier()
+    _make_elf_with_glibc_symbols(tmp_path / "java", ["2.17", "2.34"])
+    _make_elf_with_glibc_symbols(tmp_path / "libjvm.so", ["2.17", "2.28", "2.34"])
+
+    assert verifier.max_glibc_in_dir(tmp_path) == (2, 34)
+
+
+def test_parse_wheel_tag_extracts_version_and_arch(tmp_path: Path) -> None:
+    verifier = _load_verifier()
+    wheel = tmp_path / "arcadedb_embedded-26.4.2-py3-none-manylinux_2_34_x86_64.whl"
+    wheel.write_bytes(b"")
+
+    glibc, arch = verifier.parse_wheel_tag(wheel)
+    assert glibc == (2, 34)
+    assert arch == "x86_64"
+
+
+def test_main_succeeds_when_tag_matches(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    verifier = _load_verifier()
+    jre_dir = tmp_path / "jre"
+    jre_dir.mkdir()
+    _make_elf_with_glibc_symbols(jre_dir / "libjvm.so", ["2.17", "2.34"])
+
+    wheel = tmp_path / "arcadedb_embedded-26.4.2-py3-none-manylinux_2_34_x86_64.whl"
+    wheel.write_bytes(b"")
+
+    rc = _run_main(verifier, [str(wheel), str(jre_dir)])
+    assert rc == 0
+    assert "OK" in capsys.readouterr().out
+
+
+def test_main_fails_when_tag_higher_than_jre(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    """Reproduces issue #4037: wheel tagged manylinux_2_35 but JRE only needs GLIBC_2.34."""
+    verifier = _load_verifier()
+    jre_dir = tmp_path / "jre"
+    jre_dir.mkdir()
+    _make_elf_with_glibc_symbols(jre_dir / "libjvm.so", ["2.17", "2.34"])
+
+    wheel = tmp_path / "arcadedb_embedded-26.4.2-py3-none-manylinux_2_35_x86_64.whl"
+    wheel.write_bytes(b"")
+
+    rc = _run_main(verifier, [str(wheel), str(jre_dir)])
+    captured = capsys.readouterr()
+    assert rc != 0
+    assert "does not match" in captured.err
+    assert "manylinux_2_35" in captured.err or "manylinux_2_34" in captured.err
+
+
+def test_main_fails_when_tag_lower_than_jre(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    """A too-low tag would let the wheel install on systems where the JRE cannot run."""
+    verifier = _load_verifier()
+    jre_dir = tmp_path / "jre"
+    jre_dir.mkdir()
+    _make_elf_with_glibc_symbols(jre_dir / "libjvm.so", ["2.17", "2.36"])
+
+    wheel = tmp_path / "arcadedb_embedded-26.4.2-py3-none-manylinux_2_28_x86_64.whl"
+    wheel.write_bytes(b"")
+
+    rc = _run_main(verifier, [str(wheel), str(jre_dir)])
+    assert rc != 0
+    assert "does not match" in capsys.readouterr().err
+
+
+def _run_main(verifier, argv: list[str]) -> int:
+    import sys
+
+    saved = sys.argv
+    sys.argv = ["verify_wheel_platform_tag.py", *argv]
+    try:
+        return verifier.main()
+    finally:
+        sys.argv = saved
+
+
+def test_module_exposes_public_api() -> None:
+    """Sanity check: the verifier module imports without errors and exposes its API."""
+    verifier = _load_verifier()
+    assert hasattr(verifier, "max_glibc_in_dir")
+    assert hasattr(verifier, "parse_wheel_tag")
+    assert hasattr(verifier, "main")