[Bug] README “Build from Source” instructions outdated. "gremlin-console.sh" fails on Mac M4 (Apple Silicon)

[vaijosh]

Bug Type (问题类型)

other exception / error (其他异常报错)

Before submit

• 我已经确认现有的 Issues 与 FAQ 中没有相同 / 重复问题 (I have confirmed and searched that there are no similar problems in the historical issue and documents)

Environment (环境信息)

• Server Version: 1.0.0 (Apache Release Version)
• Backend: RocksDB x nodes, HDD or SSD
• OS: xx CPUs, xx G RAM, Ubuntu 2x.x / CentOS 7.x
• Data Size: xx vertices, xx edges

Expected & Actual behavior (期望与实际表现)

Description:

• The README’s “Build from Source” instructions are outdated and do not match the current directory structure and startup instructions after building from source. As a result, users cannot start the server as described.
• Additionally, the bundled Gremlin Console (bin/gremlin-console.sh) fails to start on Mac M4 (Apple Silicon) due to native library (Jansi) incompatibility and Java version issues.

Details:

• After building from source, the server scripts are not in the location described in the README, causing startup failures.
• On Mac M4, running Gremlin Console results in errors like: java.lang.UnsatisfiedLinkError: Could not load library. Reasons: [no jansi in java.library.path ... (fat file, but missing compatible architecture (have 'x86_64,i386', need 'arm64'))] and the gremlin console works only with Java 11

Proposed Fix:

• Update the README to reflect the correct post-build directory structure and server startup steps.
• Add troubleshooting notes for Apple Silicon and Java 17+ users regarding Gremlin Console

Vertex/Edge example (问题点 / 边数据举例)

Schema [VertexLabel, EdgeLabel, IndexLabel] (元数据结构)

[dosubot]

Hi @vaijosh! I'm Dosu and I’m helping the hugegraph team.

@vaijosh — both issues you've identified are real and have been encountered before.

Build from Source instructions: The README directs users to install-dist/target/hugegraph-{version}.tar.gz, but the actual build output places artifacts at the root level (apache-hugegraph-${version}/) and within individual component directories (hugegraph-pd/, hugegraph-store/, hugegraph-server/) [1] [2]. So the post-build paths are indeed outdated.

Gremlin Console on Apple Silicon: The Jansi native library crash on ARM64 is a documented problem [3]. The bundled Jansi only ships with x86_64 and i386 binaries, so it fails on arm64. The recommended workaround for startup/detection scripts has been to replace Gremlin Console–based logic with PD REST health checks [3]. Several related ARM64 fixes have been merged over time, including JNA upgrades for Mac M1 (PR #2013) and multi-architecture Docker support (PR #2903).

Java version: Gremlin Console works with Java 8 and Java 11. Java 17+ fails due to Groovy 2.5.14 not supporting Java 17 bytecode [4], so restricting to Java 11 is the right call for now.

Your proposed fixes — updating the README paths and adding Apple Silicon / Java 17+ troubleshooting notes — would be valuable additions. There's currently no official troubleshooting documentation covering these issues.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.