Skip to content

Flatpak packaging - #719

Open
gattolfo98 wants to merge 2 commits into
jMonkeyEngine:masterfrom
gattolfo98:flatpak-packaging
Open

gattolfo98 wants to merge 2 commits into
jMonkeyEngine:masterfrom
gattolfo98:flatpak-packaging

Conversation

@gattolfo98

Copy link
Copy Markdown

Hi! This PR adds a Flatpak build for the SDK (app id org.jmonkeyengine.SDK).
Everything is in installers/linux-flatpak/, and there's a short doc in docs/flatpak-packaging.md on how to build and use it.

How it works

  • It doesn't build from source, it just takes dist/jmonkeyplatform.zip (the same zip the release workflow already makes)
  • Runtime is org.freedesktop.Platform//25.08
  • The full JDK comes from the openjdk25 extension and goes in /app/jdk. A JRE is not enough because the SDK needs javac to build projects

No files in the home folder

This was the main thing for me: the SDK shouldn't write anything in the user's home.

  • The flatpak has no home permission
  • Only Documents is read-write (for projects), Pictures and Downloads are read-only (to import assets)
  • The wrapper sets HOME, GRADLE_USER_HOME and -Duser.home (via JAVA_TOOL_OPTIONS), so the userdir, .gradle, .m2, .jmonkeyplatform etc. all end up in ~/.var/app/org.jmonkeyengine.SDK/
  • This also works for Gradle builds and games started from the IDE, since every JVM reads JAVA_TOOL_OPTIONS

If someone needs another folder they can just do flatpak override --user --filesystem=<folder> org.jmonkeyengine.SDK.

Workarounds in the wrapper

What Why
-DLWJGL_DISABLE_XRANDR=true LWJGL 2 runs the xrandr program, it's not in the runtime, so the 3D view crashed with an NPE in XRandR.getResolutions
_JAVA_AWT_WM_NONREPARENTING=1 Only on niri / sway / Hyprland / river / i3, otherwise Java just shows a gray window

Tested on

Fedora 44, niri, laptop with AMD + NVIDIA:

  • IDE starts and the window draws fine
  • Create and run a project
  • Scene Composer on the NVIDIA GPU

Known issue (not caused by the flatpak)

On the AMD GPU (Mesa) the Scene Composer says "OpenGL context not started", and in the log there's:

Could not find GLX 1.3 config from peer info

But this happens also with the normal zip without flatpak, so it's not from this PR.
From what I found, LWJGL 2 picks a GLX config that doesn't support windows, and then Mesa can't find it again by its id. Running on the NVIDIA GPU works.
I can open a separate issue for this if you want.

Still open

  • release.yml doesn't build the flatpak yet. I can add a job (here or in another PR) that uploads an installers-flatpak-<arch> artifact, so it gets attached to the release like the other installers
  • The <release> in the metainfo is a placeholder (3.9.0, 2026-01-01). What's the next tag going to be?
  • The screenshot url points to master, so it will only work after the merge
  • For Flathub we'd need a verification file on jmonkeyengine.org/.well-known/, but that's for later

Let me know if you want something changed!

# Keeps every file the SDK writes for itself inside ~/.var/app/org.jmonkeyengine.SDK.

REAL_HOME="$HOME"
SANDBOX_HOME="$XDG_DATA_HOME/home"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If $XDG_DATA_HOME is unset or empty, SANDBOX_HOME defaults to /home, which will fail mkdir -p inside the sandbox. Fallback to the standard XDG default path ensures SANDBOX_HOME is always valid.

Suggested change
SANDBOX_HOME="$XDG_DATA_HOME/home"
SANDBOX_HOME="${XDG_DATA_HOME:-$REAL_HOME/.local/share}/home"

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for what i knwo flatpak always sets XDG_DATA_HOME (to ~/.var/app/org.jmonkeyengine.SDK/data) and this script only runs as the flatpak entry point, so it cant be empty.

If we want a fallback anyway, i think it should be the sandbox path: SANDBOX_HOME="${XDG_DATA_HOME:-$REAL_HOME/.var/app/org.jmonkeyengine.SDK/data}/home"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point! You're completely right that Flatpak sets XDG_DATA_HOME automatically for the container environment, so keeping $XDG_DATA_HOME/home as-is works cleanly without an extra fallback.

Comment on lines +11 to +13
# $1 = XDG name (DOCUMENTS, PICTURES, DOWNLOAD), $2 = fallback folder name
target=""
if command -v xdg-user-dir >/dev/null 2>&1; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On non-English system locales, XDG user directory names are localized (e.g. Dokumente, Documenti, Téléchargements). Using xdg-user-dir when available links the actual host folders into the sandbox home while retaining a fallback to English folder names.

Suggested change
# $1 = XDG name (DOCUMENTS, PICTURES, DOWNLOAD), $2 = fallback folder name
target=""
if command -v xdg-user-dir >/dev/null 2>&1; then
for type in DOCUMENTS PICTURES DOWNLOAD; do
if command -v xdg-user-dir >/dev/null 2>&1; then
dir="$(xdg-user-dir "$type")"
else
case "$type" in
DOCUMENTS) dir="$REAL_HOME/Documents" ;;
PICTURES) dir="$REAL_HOME/Pictures" ;;
DOWNLOAD) dir="$REAL_HOME/Downloads" ;;
esac
fi
[ -d "$dir" ] && ln -sfn "$dir" "$SANDBOX_HOME/$(basename "$dir")"
done

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the current code already uses xdg-user-dir when it's available, the english name is only the fallback.
I checked inside the sandbox: xdg-user-dir is in the freedesktop runtime, and flatpak exposes the host user-dirs.dirs read-only in the app config dir. so on a localized system it already resolves to e.g. ~/Documenti and links it as Documents in the sandbox home.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's awesome—thanks for verifying that xdg-user-dir and the host user-dirs.dirs integration work out-of-the-box inside the sandbox. I'll resolve this conversation!

Comment on lines +24 to +26
link_user_dir PICTURES Pictures
link_user_dir DOWNLOAD Downloads

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Normalizing XDG_CURRENT_DESKTOP to lowercase ensures case-insensitive matching across desktop environments (e.g. hyprland vs Hyprland).

Suggested change
link_user_dir PICTURES Pictures
link_user_dir DOWNLOAD Downloads
case "$(printf '%s' "$XDG_CURRENT_DESKTOP" | tr '[:upper:]' '[:lower:]')" in
*niri*|*sway*|*hyprland*|*river*|*i3*)
export _JAVA_AWT_WM_NONREPARENTING=1 ;;
esac

<developer id="org.jmonkeyengine">
<name>jMonkeyEngine</name>
</developer>
<description>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The <developer_name> tag is deprecated in current AppStream specifications. Updating to <developer><name>...</name></developer> aligns with the modern AppStream standard used by Flathub and distros.

Suggested change
<description>
<developer>
<name>jMonkeyEngine Team</name>
</developer>

Comment on lines +34 to +36
<content_rating type="oars-1.1"/>
<releases>
<!-- <release version="3.9.0" date="2026-01-01"/> -->

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An empty <releases> element containing only commented-out code triggers an appstreamcli validate error (tag-missing). Un-commenting or providing an active <release> entry fixes AppStream validation.

Suggested change
<content_rating type="oars-1.1"/>
<releases>
<!-- <release version="3.9.0" date="2026-01-01"/> -->
<releases>
<release version="3.9.0" date="2026-01-01"/>
</releases>

@jaime-jmebot jaime-jmebot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting together this Flatpak package! The setup and documentation are very clean and straightforward.

A few minor observations and suggestions:

  • Handled localized XDG user directory resolution via xdg-user-dir so non-English desktop installs link properly.
  • Hardened default fallback for $SANDBOX_HOME if $XDG_DATA_HOME is unset.
  • Updated AppStream metainfo tags (<developer> and <release>) to pass AppStream validation cleanly.

@jaime-jmebot jaime-jmebot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An inline reply has been posted acknowledging the comment.

@jaime-jmebot jaime-jmebot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have replied to the review comment acknowledging that xdg-user-dir is provided by the Freedesktop runtime and correctly resolves localized user directories inside the sandbox.

@tonihele

Copy link
Copy Markdown
Contributor

I'm not sure about this. It adds a lot of complexity. Would it be possible for you to approach this so that you would try to contribute to NBPackage project. Have them support Flatpak and then that would be natively available to us...?

@gattolfo98

Copy link
Copy Markdown
Author

I'm not sure about this. It adds a lot of complexity. Would it be possible for you to approach this so that you would try to contribute to NBPackage project. Have them support Flatpak and then that would be natively available to us...?

I see the point about complexity. I dont know NBPackage at all. I could try to look into it and see if I can contribute, but Im not sure how much free time I have right now. Id have to evaluate how it actually works before promising anything.

I went with Flatpak initially because its kinda becoming the standard on Linux and because I didnt want NetBeans/jME files in my home folder.

If youd like, I could maintain the Flatpak packaging myself. In any case I think having it on Flathub (or Snapcraft, although I dont know the details and wouldnt know how to manage it) could give the IDE a lot of visibility.

Obviously if instead you dont want to integrate the Flatpak version theres no problem, as I said in the first place I developed it because I needed it.

In the next few days I'll finish my midterms and maybe I'll have some time to take a look at NBPackage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants