docs: add JabKit native-image how-to#16135
Draft
wanling0000 wants to merge 7 commits into
JabRef:mainJabRef/jabref:mainfrom
wanling0000:docs/jabkit-native-imagewanling0000/jabref:docs/jabkit-native-imageCopy head branch name to clipboard
Draft
docs: add JabKit native-image how-to#16135wanling0000 wants to merge 7 commits intoJabRef:mainJabRef/jabref:mainfrom wanling0000:docs/jabkit-native-imagewanling0000/jabref:docs/jabkit-native-imageCopy head branch name to clipboard
wanling0000 wants to merge 7 commits into
JabRef:mainJabRef/jabref:mainfrom
wanling0000:docs/jabkit-native-imagewanling0000/jabref:docs/jabkit-native-imageCopy head branch name to clipboard
Conversation
Contributor
PR Summary by QodoAdd developer how-to for building JabKit as a GraalVM native image
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Contributor
Code Review by Qodo
1. Phantom PDF smoke test
|
Comment on lines
+125
to
+126
| - **Locally:** install the Liberica NIK Full package that matches the project's JDK version, and point `GRAALVM_HOME` and `JAVA_HOME` at it. | ||
| - **In CI** (`jabkit-native-smoke-test.yml`): use [`graalvm/setup-graalvm`](https://github.com/graalvm/setup-graalvm#supported-distributions) with `distribution: liberica` (NIK) and `java-package: jdk+fx` (the Full package). |
Contributor
There was a problem hiding this comment.
2. Wrong ci setup instructions 🐞 Bug ≡ Correctness
The how-to instructs using graalvm/setup-graalvm with distribution: liberica in jabkit-native-smoke-test.yml, but the actual workflow uses the repo composite action setup-gradle which delegates to actions/setup-java with distribution: graalvm, so following the doc will not reproduce CI.
Agent Prompt
### Issue description
The CI setup documented in the new page does not match the actual workflow configuration.
### Issue Context
The doc specifically names `graalvm/setup-graalvm` + Liberica NIK Full, but the repo workflow uses `./.github/actions/setup-gradle` (actions/setup-java) with distribution `graalvm`.
### Fix Focus Areas
- docs/code-howtos/jabkit-native-image.md[123-127]
- .github/workflows/jabkit-native-smoke-test.yml[31-36]
- .github/actions/setup-gradle/action.yml[17-23]
### Suggested fix
Update the documentation to reflect the real CI setup (or, if the intent is to switch CI to Liberica NIK Full, update the workflow accordingly and keep the docs in sync).
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
koppor
requested changes
Jul 2, 2026
koppor
left a comment
Member
There was a problem hiding this comment.
OKish good start.
Should be more clear and more structured
first present the as-is thing and then the howto to change things and then the limitations
|
|
||
| [GraalVM Native Image](https://www.graalvm.org/latest/reference-manual/native-image/) turns JabKit into a self-contained executable that starts in milliseconds. JabKit is the first target because it is headless; the JabLS, JabSrv and JabGui come later. | ||
|
|
||
| The catch is the closed-world assumption: Native Image must know every class, method, and resource the program can use. Anything reached only through **reflection, resources, serialization, dynamic proxies, or JNI** must be declared as **reachability metadata**. Producing that metadata correctly, minimally, and with clear ownership is what most of this page is about. |
Member
There was a problem hiding this comment.
This is a bit lengthy.
- shorten
- link GraalVM documentation
Comment on lines
+42
to
+44
| ### Platform support | ||
|
|
||
| CI builds on Linux (`ubuntu-22.04`) and macOS (`macos-15`). The PDF attachment command currently works only on Linux because it uses an AWT path. See [Liberica NIK](#liberica-nik). |
Member
There was a problem hiding this comment.
?
Why not Windows would be more interesting. -- Limitations should be at the end, not in the middle.
|
|
||
| ### What the build produces on Linux | ||
|
|
||
| The build emits the `jabkit` binary plus companion `.so` files; native-image externalizes the JDK's AWT libraries. Check for `libfreetype.so` as part of that output: GraalVM CE emits `libawt.so` and `libfontmanager.so` too, but its AWT chain is incomplete, so it crashes at runtime. NIK Full completes the chain. Ship the whole `nativeCompile/` directory. |
Member
There was a problem hiding this comment.
?
I think, this can be removed
Or streamlined !!!!
say: binary and libraries and list them - not the long text. - and NOT the AWT AGAIN - AWT should be lsited at limitations once... at the end.
|
|
||
| ### macOS is a known limitation | ||
|
|
||
| Liberica NIK Full fixes the AWT path on **Linux**, verified end-to-end. On **macOS** it does not: the PDF-attachment command crashes loading `libawt_lwawt.dylib`, blocked by [oracle/graal#13272](https://github.com/oracle/graal/issues/13272) (runtime symptom: [oracle/graal#4124](https://github.com/oracle/graal/issues/4124)). The upstream fix landed in GraalVM `master` in May 2026 but is not in any released GraalVM/NIK yet; it should arrive in a future release. Until then, native PDF support on macOS is unavailable, which is why the [PDF smoke test](#smoke-testing) runs on Linux only. |
Member
There was a problem hiding this comment.
move to the end of the holw thing. we have the known AWT information aGAIN.
|
|
||
| - Assert data or exit code, not fragile status text. Check `$?`, or use `grep -c` on a known stable string in the output. | ||
| - Silence expected noise. Add `--porcelain` at the leaf command. | ||
| - If a command has no `--porcelain`, assert the exit code. Commands without `SharedOptions`, such as `preferences export`, cannot take the flag, so check `; echo $?`. |
Member
There was a problem hiding this comment.
All commands should have --porcelain.
Modify JabKit to have all comamnds supporting --porcelain (even if internally, nothing is chaniged yet)
|
|
||
| ### How to write assertions | ||
|
|
||
| - Assert data or exit code, not fragile status text. Check `$?`, or use `grep -c` on a known stable string in the output. |
Member
There was a problem hiding this comment.
What is "fragile status text"? We have --porcelain... Give an example why procelain cannot help.
Currently, its not justified...
| | --- | --- | --- | | ||
| | `jabkit-offline.md` | Commands needing no network | Linux and macOS | | ||
| | `jabkit-offline-pdf.md` | The PDF/AWT path | Linux only; see [Liberica NIK](#liberica-nik) | | ||
| | `jabkit-online.md` | Commands hitting external APIs | Opt-in with `run-online-tests` | |
Member
There was a problem hiding this comment.
run-online-tests is defined where?
Contributor
|
The requested changes were not addressed for 10 days. Please follow-up in the next 10 days or your PR will be automatically closed. You can check the contributing guidelines for hints on the pull request process. |
Co-authored-by: Oliver Kopp <kopp.dev@gmail.com>
wanling0000
marked this pull request as draft
July 13, 2026 18:28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related issues and pull requests
Closes no related issue.
This PR is part of JabRef components as native images project.
PR Description
Adds a developer how-to at
docs/code-howtos/native-image.md.Steps to test
Check the page under
code-howtos->jabkit-native-image.mdAI usage
Claude Code (model claude-opus-4-8). I used it to brainstorm the structure, draft the outline, and fill in details. All technical claims were verified against the codebase and the GraalVM documentation. I reviewed, edited, and take full ownership of the final text.
Checklist
CHANGELOG.mdin a way that can be understood by the average user (if change is visible to the user)