[Task] Support HugeGraph with RocksDB on RISC-V

[imbajin]

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
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 191 and backported it to JDK 17.0.9,2 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 uses eclipse-temurin:11-jre-jammy, whose current manifest has no linux/riscv64. eclipse-temurin:17-jre-noble has that variant,3 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 normalizes riscv64 to unknown. Newer plugin releases recognize it.4	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,5 and the generated RaftRequests.java is not committed.	Add a documented RISC-V strategy, such as a compatible system protoc through protocExecutable,6 while keeping normal builds reproducible. Merely changing unknown to riscv64 is not sufficient.
RocksDB JNI	HugeGraph pins rocksdbjni:8.10.2. 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:

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)));
}

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 and
#7060, and added a Linux/RISC-V Java
build path in #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:

java.lang.IllegalArgumentException: Unsupported class file major version 61

HugeGraph currently pins TinkerPop 3.5.1. Upstream 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

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

Loading

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:

# 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:

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

Footnotes

1. OpenJDK JEP 422: Linux/RISC-V Port ↩

2. OpenJDK RISC-V backport record (JDK 17.0.9) ↩

3. Docker Official Image metadata for Eclipse Temurin ↩

4. os-maven-plugin architecture detection ↩

5. Current protoc:3.21.7 Maven Central classifiers ↩

6. protobuf-maven-plugin custom protocExecutable option ↩

7. TINKERPOP-2633: Java 17 class-file support affecting TinkerPop 3.5.1 ↩

8. Ubuntu 24.04 OpenJDK 11 package for riscv64 ↩

9. Docker: multi-platform builds, QEMU, and cross-compilation ↩

10. GitHub: supported self-hosted runner architectures ↩

[yugaaank]

Hi @imbajin — I'd like to pick up the RocksDB smoke test work item (starter-friendly, no prerequisite). Plan: a small JUnit/Java test that asserts uname -m == riscv64, performs open/put/get/close, and fails with a clear message on the __atomic_compare_exchange_1 linkage problem. I'll link the PR back here. Let me know if anyone's already on it.

[imbajin]

Thanks @yugaaank — no one is assigned to this yet.

For the fastest first step, please do not start with a JUnit test. The main unknown is the real RISC-V runtime integration, not HugeGraph's Java logic.

If you already have SSH access to a glibc-based linux/riscv64 server, that is the simplest and preferred path:

1. Build the HugeGraph Server distribution on a supported x86-64/arm64 host, then copy it to the RISC-V server. A native RISC-V Maven/protoc build is a separate, later task.
2. On the server, verify uname -m reports riscv64, Java is Java 11, and libatomic is available (install libatomic1 if needed).
3. Configure the libatomic preload automatically for this test environment, then verify real RocksDB open/put/get/close. The undefined __atomic_compare_exchange_1 symbol must fail the check; it is not an acceptable final result.
4. Run HugeGraph init/start, /versions, REST schema + CRUD, one Gremlin query, restart, and persistence verification.
5. Capture the environment and results, then remove only the copied test files, process, and data created by the check.

If no native RISC-V server is available, run the same checks in a disposable Docker/QEMU environment and clean up its container/image/volume. QEMU is the fallback, not a requirement when native hardware is available.

Once either end-to-end path works reliably, we can decide which portable checks belong in JUnit/CI. A focused PR for a reusable Java 11 smoke helper that supports both local QEMU and an SSH target would be a great starting point.

[Seanium]

Implemented the minimum HugeGraph Server + RocksDB linux/riscv64 support in #3102.

The final scope is intentionally limited to build/runtime validation:

• an opt-in RocksDB-only distribution build, while the default reactor and distribution
  remain unchanged;
• RISC-V architecture detection plus native system protoc and
  grpc_java_plugin support;
• automatic libatomic.so.1 preload for initialization and Server startup on
  linux/riscv64;
• an isolated RISC-V Server CI job using a checksum-pinned Dragonwell 11 Extended
  Server VM under QEMU;
• real RocksDB JNI put/get/reopen, REST schema and graph CRUD, Gremlin, shutdown,
  restart persistence, and cleanup checks.

The official HugeGraph Dockerfile, image publication, existing architecture JDKs, and
existing Server jobs are not changed by this PR.

Validation on the current head:

• native RISC-V clean build: all 16 selected projects passed; PD and Store entries are
  aggregator POMs only, and no unrelated backend implementation was built or packaged;
• native RISC-V runtime: Dragonwell 11 Server VM, RocksDB JNI, REST/Gremlin, both
  shutdowns, restart persistence, and final process/port cleanup passed;
• org-hosted QEMU job
  89169639441
  passed the same build and runtime boundary in 23m17s;
• the default 43-project Java 11 reactor and existing memory/RocksDB/HBase/macOS,
  PD/Store/HStore checks were retained.

The six Apache workflows for the exact head still require maintainer approval. The org
results above are not represented as Apache workflow results. QEMU and the available
native machine establish functional correctness, not production performance or
sustained-load qualification.