imbajin opened a new issue, #3099: URL: https://github.com/apache/hugegraph/issues/3099
<!-- Title: [Task] Support HugeGraph with RocksDB on RISC-V Issue type: Task Labels: feature, ci-cd, tests, java, rocksdb, doc, help wanted, good first issue This is a reviewed draft. Please keep this as one umbrella issue and link implementation PRs here. --> ## Goal Make **HugeGraph Server with the embedded RocksDB backend** build, start, store data, restart, and pass its core tests on `linux/riscv64`. This task should also provide a reproducible Docker/QEMU workflow so that contributors can develop and test the port on a normal x86-64 or arm64 computer without owning a RISC-V device. ## Scope In scope: - `hugegraph-server` - the `rocksdb` backend and its native JNI library - a Server/RocksDB-only source and packaging target for `linux/riscv64` - a runnable `linux/riscv64` Server image - automated RocksDB and HugeGraph smoke/regression tests - contributor and support documentation Out of scope: - HugeGraph PD, Store, and HStore - Cassandra, HBase, MySQL, PostgreSQL, ScyllaDB, and every other backend - RISC-V performance certification or tuning - 32-bit RISC-V and musl/Alpine support The current standard Server distribution depends on and packages other backend modules. That does **not** put those backends into scope: this task should add a RocksDB-only build/package selection (or an equally explicit exclusion mechanism) so unrelated backend build failures do not become RISC-V requirements. If the normal universal tarball continues to carry other backend JARs, they remain untested and unsupported on RISC-V by this task. Please coordinate all RISC-V Server/RocksDB work in this issue and link PRs here instead of opening duplicate umbrella issues. ## Why work is needed HugeGraph is mostly Java, but RocksDB is an embedded native library. A successful Java compile or `RocksDB.loadLibrary()` call is therefore not enough to claim RISC-V support. The build toolchain, JNI binary, C/C++ runtime, Docker base image, and real database I/O must all work together. The findings below were checked against HugeGraph commit [`a802912`](https://github.com/apache/hugegraph/commit/a80291223cc696ecb8d6696e64fd57fd1c90b9f0) on 2026-07-20. | Area | Confirmed current state | What the task must solve | |---|---|---| | Java | HugeGraph sets Java source/target 11, accepts JDK 11+, and pins TinkerPop 3.5.1. OpenJDK delivered its Linux/RISC-V port in JDK 19 and backported it to JDK 17.0.9, but TinkerPop 3.5.1 is affected by a known Java 17 class-reader failure. | Select and fully test one supported path: a suitably maintained RISC-V JDK 11 runtime, or the dependency work needed for the complete Gremlin stack to run on JDK 17+. Keep a real JDK 11 compatibility gate for existing users. | | Runtime image | [`hugegraph-server/Dockerfile`](https://github.com/apache/hugegraph/blob/a80291223cc696ecb8d6696e64fd57fd1c90b9f0/hugegraph-server/Dockerfile#L33-L35) uses `eclipse-temurin:11-jre-jammy`, whose current manifest has no `linux/riscv64`. `eclipse-temurin:17-jre-noble` has that variant, and Ubuntu 24.04 also publishes an OpenJDK 11 RISC-V package. | Choose a maintained glibc-based image/JDK combination based on a full Server test, not manifest availability or `/versions` alone. | | Native Maven build | [`os-maven-plugin:1.5.0.Final`](https://github.com/apache/hugegraph/blob/a80291223cc696ecb8d6696e64fd57fd1c90b9f0/hugegraph-server/hugegraph-core/pom.xml#L334-L340) normalizes `riscv64` to `unknown`. Newer plugin releases recognize it. | Upgrade/fix architecture detection. | | Protobuf generation | The build downloads `protoc:3.21.7` using `${os.detected.classifier}`. Maven Central has no `linux-riscv64` executable for that version, and the generated `RaftRequests.java` is not committed. | Add a documented RISC-V strategy, such as a compatible system `protoc` through `protocExecutable`, while keeping normal builds reproducible. Merely changing `unknown` to `riscv64` is not sufficient. | | RocksDB JNI | HugeGraph pins [`rocksdbjni:8.10.2`](https://github.com/apache/hugegraph/blob/a80291223cc696ecb8d6696e64fd57fd1c90b9f0/hugegraph-server/hugegraph-rocksdb/pom.xml#L37-L41). Its JAR contains `librocksdbjni-linux-riscv64.so`, but a real QEMU RISC-V `open/put/get/close` test fails with `undefined symbol: __atomic_compare_exchange_1`. | Supply a JNI library correctly linked to `libatomic`, or package and configure an explicit, documented runtime solution. A version bump alone is not proof. | | Distribution | The assembly copies runtime JARs, including `rocksdbjni`, into the Server distribution, but `hugegraph-dist` currently depends on all backend modules. | Preserve a platform-neutral tarball where possible, while providing an explicit RocksDB-only build/package target that does not require RISC-V support from unrelated backends. | | CI and release image | Current Server/RocksDB CI runs on x86-64 Linux and Intel/arm64 macOS. Docker CI performs a native `docker build` and checks only that a health check is declared. Published `hugegraph/hugegraph` manifests currently have amd64 and arm64 variants, not riscv64. | Add an actual RISC-V build-and-run gate and publish a riscv64 image variant when it passes. | ## Confirmed RocksDB failure The current `rocksdbjni:8.10.2` RISC-V library is a glibc `ELF 64-bit` LP64D shared object. Inspecting it shows an unresolved `__atomic_compare_exchange_1` symbol but no `libatomic` entry in its dynamic dependencies. A Java test that performs real work fails under QEMU: ```java RocksDB.loadLibrary(); try (Options options = new Options().setCreateIfMissing(true); RocksDB db = RocksDB.open(options, "/tmp/rocksdb-smoke")) { db.put("key".getBytes(UTF_8), "value".getBytes(UTF_8)); assertArrayEquals("value".getBytes(UTF_8), db.get("key".getBytes(UTF_8))); } ``` ```text java: symbol lookup error: .../librocksdbjni-linux-riscv64.so: undefined symbol: __atomic_compare_exchange_1 ``` The same test passed after installing Ubuntu's `libatomic1` and preloading `/usr/lib/riscv64-linux-gnu/libatomic.so.1`. This proves a feasible direction, but the final solution should not depend on an undocumented command that every user must discover. `rocksdbjni:8.11.4` was also checked and showed the same failure without the workaround, so simply upgrading to that version is not an acceptance criterion. RocksDB has previously tracked the same RISC-V atomic-linking requirement in [#7051](https://github.com/facebook/rocksdb/issues/7051) and [#7060](https://github.com/facebook/rocksdb/pull/7060), and added a Linux/RISC-V Java build path in [#12139](https://github.com/facebook/rocksdb/pull/12139). ## Confirmed Java runtime blocker A current-HEAD Server distribution was built offline in an isolated temporary Maven repository and started under QEMU on `linux/riscv64`. With Temurin 17 and the `libatomic` workaround, `init-store` completed, `GET /versions` returned HTTP 200, and a vertex created through REST was still readable after a stop/start cycle. However, the Gremlin engine failed and `POST /gremlin` returned HTTP 400: ```text java.lang.IllegalArgumentException: Unsupported class file major version 61 ``` HugeGraph currently pins TinkerPop 3.5.1. Upstream [TINKERPOP-2633](https://issues.apache.org/jira/browse/TINKERPOP-2633) records the same Java 17 error for 3.5.1 and marks it fixed in 3.7.0. Therefore a successful health-like endpoint on JDK 17 is not sufficient evidence that HugeGraph Server is functional. Ubuntu 24.04 publishes `openjdk-11-jre-headless` for `riscv64`, so a JDK 11-based runtime is another candidate. The implementation should compare maintenance/update guarantees and integration cost, choose one supported route, and then run the complete RocksDB, REST, and Gremlin acceptance suite. This issue should not assume that either a base-image swap or a TinkerPop version bump is safe without that validation. ## Target build and test flow ```mermaid flowchart LR A["Developer or CI<br/>x86-64 / arm64"] --> B["Build Server distribution<br/>on supported build platform"] B --> C["Assemble<br/>linux/riscv64 image"] C --> D["Run with Docker + QEMU"] D --> E["Assert uname -m = riscv64"] E --> F["RocksDB open / put / get / close"] F --> G["HugeGraph init / start / REST CRUD"] G --> H["Restart and verify persistence"] I["Native or hosted<br/>RISC-V machine"] --> J["RocksDB-only Maven build<br/>with documented protoc"] J --> E ``` The existing Docker build stage already uses `FROM --platform=$BUILDPLATFORM`, which is a useful foundation: Java artifacts can be built on the contributor's native platform, then copied into a RISC-V runtime image. Native Maven builds on RISC-V must still be fixed and tested separately because of the `os-maven-plugin` and `protoc` problems above. ## Suggested implementation work These items may be delivered as small, linked PRs while this remains the single tracking issue. **New contributors do not need to solve the whole issue.** Please comment before claiming one row, keep each PR focused, and link it back here. | Work item | Expected output | Prerequisite | Starter-friendly | |---|---|---|---| | RocksDB smoke test | A small test that asserts `riscv64` and performs `open/put/get/close`, with a useful failure message | None | Yes | | Manifest/document check | A documented command that verifies the JDK and HugeGraph image platforms | None | Yes | | QEMU helper and cleanup | One script that runs a disposable RISC-V container and removes only what it created | RocksDB smoke test | Yes | | RISC-V Java runtime | A documented decision between a maintained JDK 11 path and validated TinkerPop/Gremlin support on JDK 17+, with a full Server test | Manifest check | Advanced | | RocksDB atomic linkage | A correctly linked JNI artifact, or an automatic and tested `libatomic1` runtime configuration | RocksDB smoke test | Advanced | | RocksDB-only packaging | A source/package target that includes Server + RocksDB without requiring unrelated backend modules | Build design agreement | Advanced | | Native Maven toolchain | `riscv64` detection plus a compatible, reproducible `protoc` executable | RocksDB-only packaging | Advanced | | End-to-end smoke | Init, start, health check, REST CRUD, a Gremlin query, restart, and persistence verification | Runtime + JNI + packaging | Moderate | | CI and release | PR/nightly QEMU jobs, native validation record, and a published image variant | End-to-end smoke | Advanced | ## How contributors can test without RISC-V hardware Docker Desktop already includes QEMU support for multi-platform builds. On Linux, BuildKit may provide emulators; if manual `binfmt_misc` registration is required, follow Docker's official setup and cleanup instructions rather than installing host packages as part of the HugeGraph build. The implementation should add one reproducible helper (name shown as an example) so the contributor workflow is small and the cleanup is not left to guesswork: ```bash # Emulator preflight only; this is not yet the supported HugeGraph runtime image docker run --rm --platform linux/riscv64 \ eclipse-temurin:17-jre-noble uname -m # Build, start in the background, wait for health, perform RocksDB + REST CRUD # and a Gremlin query, restart, verify persistence, and remove only created resources. hugegraph-server/hugegraph-dist/src/assembly/travis/run-riscv64-smoke.sh ``` The helper should use unique test names and a shell `trap`, and should end with output that makes the covered architecture and cleanup obvious: ```text PASS architecture: riscv64 PASS RocksDB: open / put / get / close PASS HugeGraph: init / health / REST CRUD / Gremlin / restart / persistence PASS cleanup: test container, volume, image, and builder removed ``` CI can use an x86-64/arm64 GitHub runner as the coordinator and run the RISC-V image with QEMU. GitHub's self-hosted runner application currently lists only x64, ARM64, and ARM32 as supported processor architectures, so native RISC-V validation should be invoked from a supported coordinator (for example over SSH) or run in an external RISC-V CI service. QEMU is a correctness tool, not a performance benchmark, and Docker notes that emulated compilation/compression can be much slower than native execution. ## Implementation and CI acceptance All of the following are required: - [ ] The documented target is 64-bit glibc Linux on RISC-V. The selected JDK, libc, libstdc++, libgcc, and RocksDB ABI requirements are explicit. For reference, the current 8.10.2 JNI binary requires LP64D and glibc symbols up to `GLIBC_2.30`. - [ ] Existing JDK 11 clean compile/tests remain green. If a newer JDK builds the artifacts, Java 11 API compatibility is enforced with `--release 11` or an equivalent check; source/target class-file version alone is not sufficient. - [ ] The selected RISC-V JDK starts the complete Server, including the Gremlin engine; logs contain no `Unsupported class file major version` error. If JDK 17+ is used, the TinkerPop/Groovy compatibility work and regression coverage are included. - [ ] A clean RISC-V Maven build of the new Server/RocksDB-only target succeeds with a documented, reproducible `protoc` strategy. It must not require building or validating HStore or any other backend. - [ ] A normal x86-64 or arm64 contributor can build the Server distribution and `linux/riscv64` image without physical RISC-V hardware. - [ ] Inside the test environment, `uname -m` reports `riscv64`. - [ ] RocksDB performs `open/put/get/close` without `UnsatisfiedLinkError`, missing atomic symbols, or undocumented manual environment changes. - [ ] With the default RocksDB backend and compression, HugeGraph initialization and startup succeed; `GET /versions` returns successfully. - [ ] A test creates schema, vertices, and an edge, reads them back, restarts the Server, verifies that the data is still present, and successfully executes a Gremlin query. - [ ] The RocksDB `core-test` and `api-test` profiles pass on RISC-V. Their new RocksDB-only helper/dependency selection must not build or test other backends. The API gate must build the selected distribution, start it, wait for health, run `api-test,rocksdb`, stop it, and clean up; a bare Maven API-test command is not an independent gate. - [ ] The Server/RocksDB image passes startup, health, CRUD, restart, and persistence smoke tests on `linux/amd64`, `linux/arm64`, and `linux/riscv64`; changing the Java base image or `libatomic` setup must not regress the two existing Linux platforms. - [ ] Documentation includes the no-hardware workflow, expected QEMU slowdown, known limitations, and commands to remove the test container, image, builder, and any manually registered emulator. ## Release/support gate - [ ] At least one native RISC-V machine or hosted RISC-V VM runs the same complete helper, including the Gremlin query and persistence check, and links its environment/result here. Any skipped or failed step makes the gate fail. - [ ] The published HugeGraph Server tag is inspected after publication and contains `linux/amd64`, `linux/arm64`, and `linux/riscv64`. The tested per-platform image digests match the entries in that manifest, so adding RISC-V cannot overwrite the existing variants. - [ ] Only after both checks pass do the release notes advertise Server + RocksDB on `linux/riscv64` as supported. ## References - [OpenJDK JEP 422: Linux/RISC-V Port](https://openjdk.org/jeps/422) - [OpenJDK RISC-V backport record (JDK 17.0.9)](https://bugs.openjdk.org/browse/JDK-8276799) - [Docker: multi-platform builds, QEMU, and cross-compilation](https://docs.docker.com/build/building/multi-platform/) - [Docker Official Image metadata for Eclipse Temurin](https://github.com/docker-library/official-images/blob/master/library/eclipse-temurin) - [Ubuntu 24.04 OpenJDK 11 package for riscv64](https://packages.ubuntu.com/noble/riscv64/openjdk-11-jre-headless/download) - [TINKERPOP-2633: Java 17 class-file support affecting TinkerPop 3.5.1](https://issues.apache.org/jira/browse/TINKERPOP-2633) - [GitHub: supported self-hosted runner architectures](https://docs.github.com/en/actions/reference/runners/self-hosted-runners#supported-processor-architectures) - [Current `protoc:3.21.7` Maven Central classifiers](https://repo1.maven.org/maven2/com/google/protobuf/protoc/3.21.7/) - [`protobuf-maven-plugin` custom `protocExecutable` option](https://www.xolstice.org/protobuf-maven-plugin/usage.html) - [`os-maven-plugin` architecture detection](https://github.com/trustin/os-maven-plugin) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
