Support running HugeGraph on Linux/RISC-V (riscv64)

[imbajin]

Goal

Make Apache HugeGraph build, run, and be testable on Linux/RISC-V 64-bit (riscv64).

This is a tracking task for newcomers and contributors who may not own RISC-V hardware. The first useful outcome is not necessarily a full production-ready port; a reproducible smoke-test path is already valuable.

Why this is feasible now

• OpenJDK integrated the Linux/RISC-V port in JDK 19 via JEP 422. The port targets 64-bit Linux/RISC-V and includes the interpreter plus C1/C2 JITs.
• Debian now has an official riscv64 port, and Debian package pages list OpenJDK packages for riscv64 (for example openjdk-17-jre).
• QEMU officially supports both RISC-V system emulation and user-mode emulation:
  • QEMU RISC-V system emulator
  • QEMU user-mode emulation
• Docker Buildx supports multi-platform images and QEMU-based emulation. Docker documents QEMU as the easiest way to start, while warning that it can be much slower for compilation-heavy work: Docker multi-platform builds.

flowchart LR
    Dev[Developer laptop / x86_64 CI] --> Buildx[Docker Buildx]
    Buildx --> QEMU[QEMU binfmt emulation]
    QEMU --> RV[linux/riscv64 container]
    RV --> Smoke[HugeGraph smoke tests]
    Smoke --> Native[Optional native RISC-V runner later]

Loading

Current HugeGraph-specific context

The RISC-V work is mostly about native/runtime dependencies and reproducible CI, not only Java source compatibility.

Area	Current observation	Why it matters
Java level	HugeGraph compiles with Java 11 target (maven.compiler.source/target=11).	Linux/RISC-V support is stronger in newer JDK lines; JDK 17+ is the practical baseline to verify first.
Docker runtime image	hugegraph-server/Dockerfile currently uses eclipse-temurin:11-jre-jammy.	Docker Official Images metadata shows newer eclipse-temurin:*‑jre‑noble tags include riscv64, while current 11/jammy tags may not. See docker-library/official-images metadata.
RocksDB JNI	hugegraph-server/hugegraph-rocksdb uses rocksdbjni:8.10.2; PD uses 6.29.5; Store uses 7.7.3.	Local jar inspection shows 8.10.2 includes librocksdbjni-linux-riscv64.so, while 6.29.5 and 7.7.3 do not. PD/Store may fail on riscv64 until their RocksDB JNI path is upgraded or rebuilt.
JNA	HugeGraph core uses JNA 5.12.1.	Local jar inspection shows linux-riscv64/libjnidispatch.so exists, so JNA is likely not the first blocker.
Protobuf/gRPC code generation	HugeGraph uses Maven classifier-based protoc / protoc-gen-grpc-java executables.	Maven Central listings for current/modern versions checked here do not show linux-riscv64 executables, so full source builds on native riscv64 may need generated sources, distro protoc, or a build-time workaround.
GitHub-hosted runners	GitHub-hosted runners document x64 and ARM runners, but not hosted RISC-V runners.	Long-term native CI probably needs a self-hosted RISC-V runner or a cloud RISC-V VM. See GitHub-hosted runners and self-hosted runners.

Suggested contributor workflow without RISC-V hardware

Layer 1: Fast static checks on any machine

# identify native/JNI dependencies
rg -n "rocksdbjni|jna|protoc|protoc-gen-grpc-java|os.detected.classifier" \
  pom.xml hugegraph-*/**/pom.xml

# inspect whether a dependency jar contains riscv64 native libraries
jar tf ~/.m2/repository/org/rocksdb/rocksdbjni/8.10.2/rocksdbjni-8.10.2.jar \
  | grep riscv64

Layer 2: Emulated riscv64 smoke tests with Docker + QEMU

# one-time setup on Linux hosts if binfmt is not already configured
docker run --privileged --rm tonistiigi/binfmt --install all

# verify builder-supported platforms
docker buildx inspect --bootstrap

# run a riscv64 userspace smoke test
docker run --rm --platform linux/riscv64 debian:sid uname -m

Expected output:

riscv64

Then test the Java runtime:

docker run --rm --platform linux/riscv64 eclipse-temurin:17-jre-noble java -version

Layer 3: HugeGraph runtime smoke test

Recommended first target:

1. Build HugeGraph distribution on the normal host architecture.
2. Build or assemble a linux/riscv64 runtime image using a RISC-V-capable JRE base image.
3. Start HugeGraph with a backend that has the fewest native dependencies first.
4. Call /versions and run a minimal Gremlin/REST smoke test.

Build on amd64/arm64
        |
        v
Copy HugeGraph dist into linux/riscv64 runtime image
        |
        v
Start HugeGraph under QEMU
        |
        v
GET /versions + minimal graph CRUD

Layer 4: Native/full validation later

After the emulated path is stable, add one of:

• a self-hosted GitHub Actions runner on real RISC-V hardware,
• a rented RISC-V cloud VM,
• or a periodically triggered manual workflow maintained by the community.

This is needed because QEMU is good for compatibility smoke tests, but it is slower and may not catch all performance or native-runtime issues.

Proposed scope

• Document the intended support target: linux/riscv64, Java 17+ first, Java 11 only if practical.
• Audit all native/JNI dependencies used by Server, PD, Store, and HStore.
• Align or upgrade RocksDB JNI usage so Server/PD/Store can load a riscv64 native library.
• Decide how to handle protobuf/gRPC code generation on native riscv64.
• Add a local developer guide for QEMU/Docker-based riscv64 smoke testing.
• Add an optional CI workflow or manual job for linux/riscv64 Docker smoke tests.
• Later: add a native RISC-V self-hosted runner or cloud runner for slower/full tests.

Acceptance criteria

• A developer without RISC-V hardware can run a documented command sequence and see HugeGraph start under linux/riscv64 emulation.
• The smoke test verifies at least:
  • uname -m reports riscv64;
  • java -version works inside the selected runtime image;
  • HugeGraph starts successfully;
  • GET /versions succeeds;
  • one minimal graph operation works.
• Known unsupported modules/backends are explicitly documented instead of failing mysteriously.

Notes for newcomers

This issue can be split into smaller PRs:

1. dependency audit only,
2. Docker/QEMU developer documentation,
3. Server-only smoke test,
4. PD/Store/HStore follow-up,
5. CI workflow follow-up.

Starting with documentation plus one reproducible smoke test is enough to make progress.

[imbajin]

Closing this premature draft: the research and scope review were not complete. Any follow-up should be a single consolidated issue focused only on HugeGraph Server with the RocksDB backend on linux/riscv64.