You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hugegraph.apache.org by "vaijosh (via GitHub)" <gi...@apache.org> on 2026/05/11 11:37:22 UTC
[PR] [Bug] Update README “Build from Source” instructions and add Gremlin Console troubleshooting for Mac M4 (Apple Silicon) (#3006) [hugegraph]
vaijosh opened a new pull request, #3022:
URL: https://github.com/apache/hugegraph/pull/3022
## Purpose of the PR
- close #3006
This PR updates the documentation to address two key issues:
- The “Option 3: Build from Source” instructions in the README were outdated and did not match the actual directory structure or server startup process after building from source.
- The bundled `gremlin-console.sh` fails on Apple Silicon (Mac M4) and with Java 17+ due to native library (Jansi) incompatibility and Java version requirements.
## Main Changes
- Updated the README to provide correct server startup steps after building from source, reflecting the actual directory structure.
- Added a troubleshooting note in the “Verify Installation” section to inform users that `gremlin-console.sh` requires Java 11 and may fail on Apple Silicon (M1/M2/M3/M4) or with Java 17+.
- Provided clear guidance and workarounds for users on affected platforms.
## Verifying these changes
- [x] Trivial rework / doc update without any test coverage. (No Need)
## Does this PR potentially affect the following parts?
- [ ] Dependencies ([add/update license](https://hugegraph.apache.org/docs/contribution-guidelines/contribute/#321-check-licenses) info & [regenerate_known_dependencies.sh](../install-dist/scripts/dependency/regenerate_known_dependencies.sh))
- [ ] Modify configurations
- [ ] The public API
- [ ] Other affects (typed here)
- [x] Nope
## Documentation Status
- [x] `Doc - Done` <!-- Related docs have been already added or updated -->
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: update "Build from Source" instructions in README [hugegraph]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin merged PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] fix: update README & adapter Gremlin Console for Mac M4 [hugegraph]
Posted by "vaijosh (via GitHub)" <gi...@apache.org>.
vaijosh commented on PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022#issuecomment-4494799514
> Thanks for the PR. I checked this locally on macOS arm64 and I think there are two separate issues here.
>
> First, the README build-from-source path is indeed outdated. The actual full distribution is produced as `target/apache-hugegraph-${version}.tar.gz`, and the server scripts are under `apache-hugegraph-${version}/apache-hugegraph-server-${version}/bin/`, not directly under `install-dist/target/hugegraph-{version}`. This part should be fixed as a documentation-only change and does not require adding a new dependency.
>
> Second, the Apple Silicon Gremlin Console failure is real, but it is a separate compatibility problem in the current TinkerPop 3.5.1 / JLine / Jansi stack. Adding `jansi:2.4.0` may be a possible workaround, but it is not the minimal fix for the README issue itself. If we want to claim that bundled `bin/gremlin-console.sh` works on Apple Silicon, we should add a macOS arm64 smoke test that actually runs the console, for example on `macos-15`:
>
> ```shell
> VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
> SERVER_DIR="hugegraph-server/apache-hugegraph-server-${VERSION}"
> printf "println \"gremlin-console-smoke-ok\"\n" > "$RUNNER_TEMP/gremlin-console-smoke.groovy"
> "${SERVER_DIR}/bin/gremlin-console.sh" -- -e "$RUNNER_TEMP/gremlin-console-smoke.groovy"
> ```
>
> Also, we are preparing to upgrade TinkerPop to 3.8. Since the official TinkerPop 3.8 Gremlin Console artifacts are already available and the current TinkerPop download page lists Gremlin Console / Server compatibility with Java 11/17, I think we should first verify whether the TinkerPop 3.8 upgrade already resolves the Jansi/JLine native-library issue before introducing a new direct dependency here.
>
> So I would suggest splitting this PR:
>
> 1. README path correction only, no dependency change.
> 2. A separate Apple Silicon Gremlin Console compatibility fix, with macOS arm64 CI coverage if we decide to support the bundled console before the TinkerPop upgrade.
Hi @imbajin,
I have implemented the review comments. Separated the README.md changes from mac m4 issues.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] fix: [Bug] README “Build from Source” instructions outdated. #3006 [hugegraph]
Posted by "vaijosh (via GitHub)" <gi...@apache.org>.
vaijosh commented on PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022#issuecomment-4494859232
Created separate issue https://github.com/apache/hugegraph/issues/3031 for gremlin-console.sh errors on Mac M4
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] fix: update README & adapter Gremlin Console for Mac M4 [hugegraph]
Posted by "vaijosh (via GitHub)" <gi...@apache.org>.
vaijosh commented on PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022#issuecomment-4489663591
Thanks @imbajin for the feedback.
I will create a separate ticket and PR for Mac issue. I will keep only readme changes in here.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] fix: update README & adapter Gremlin Console for Mac M4 [hugegraph]
Posted by "codecov[bot] (via GitHub)" <gi...@apache.org>.
codecov[bot] commented on PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022#issuecomment-4490068040
## [Codecov](https://app.codecov.io/gh/apache/hugegraph/pull/3022?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 0.07%. Comparing base ([`8d095e1`](https://app.codecov.io/gh/apache/hugegraph/commit/8d095e1d9901208f6cc03d3d5b06c975ec096e55?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`644b437`](https://app.codecov.io/gh/apache/hugegraph/commit/644b4373f4f17568a003a86807b5cd0cd221a0e3?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
:warning: Report is 1 commits behind head on master.
> :exclamation: There is a different number of reports uploaded between BASE (8d095e1) and HEAD (644b437). Click for more details.
>
> <details><summary>HEAD has 3 uploads less than BASE</summary>
>
>| Flag | BASE (8d095e1) | HEAD (644b437) |
>|------|------|------|
>||4|1|
></details>
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## master #3022 +/- ##
============================================
- Coverage 36.15% 0.07% -36.08%
+ Complexity 403 22 -381
============================================
Files 812 781 -31
Lines 68307 65525 -2782
Branches 8927 8457 -470
============================================
- Hits 24694 51 -24643
- Misses 40978 65472 +24494
+ Partials 2635 2 -2633
```
</details>
[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/apache/hugegraph/pull/3022?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
<details><summary> :rocket: New features to boost your workflow: </summary>
- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] fix: update README & adapter Gremlin Console for Mac M4 [hugegraph]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on PR #3022:
URL: https://github.com/apache/hugegraph/pull/3022#issuecomment-4488697601
Thanks for the PR. I checked this locally on macOS arm64 and I think there are two separate issues here.
First, the README build-from-source path is indeed outdated. The actual full distribution is produced as `target/apache-hugegraph-${version}.tar.gz`, and the server scripts are under `apache-hugegraph-${version}/apache-hugegraph-server-${version}/bin/`, not directly under `install-dist/target/hugegraph-{version}`. This part should be fixed as a documentation-only change and does not require adding a new dependency.
Second, the Apple Silicon Gremlin Console failure is real, but it is a separate compatibility problem in the current TinkerPop 3.5.1 / JLine / Jansi stack. Adding `jansi:2.4.0` may be a possible workaround, but it is not the minimal fix for the README issue itself. If we want to claim that bundled `bin/gremlin-console.sh` works on Apple Silicon, we should add a macOS arm64 smoke test that actually runs the console, for example on `macos-15`:
```bash
VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
SERVER_DIR="hugegraph-server/apache-hugegraph-server-${VERSION}"
printf "println \"gremlin-console-smoke-ok\"\n" > "$RUNNER_TEMP/gremlin-console-smoke.groovy"
"${SERVER_DIR}/bin/gremlin-console.sh" -- -e "$RUNNER_TEMP/gremlin-console-smoke.groovy"
```
Also, we are preparing to upgrade TinkerPop to 3.8. Since the official TinkerPop 3.8 Gremlin Console artifacts are already available and the current TinkerPop download page lists Gremlin Console / Server compatibility with Java 11/17, I think we should first verify whether the TinkerPop 3.8 upgrade already resolves the Jansi/JLine native-library issue before introducing a new direct dependency here.
So I would suggest splitting this PR:
1. README path correction only, no dependency change.
2. A separate Apple Silicon Gremlin Console compatibility fix, with macOS arm64 CI coverage if we decide to support the bundled console before the TinkerPop upgrade.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org