Keep the browse fix from aborting headless runs

[danielvartan]

Problem

The browse fix agent was attached to every jpackage launcher with an absolute path:

java-options=-javaagent:/app/opt/netlogo/lib/app/browse-fix.jar

A -javaagent that the JVM cannot open is fatal at VM init, so any launch where that exact path does not resolve dies before NetLogo starts:

Error opening zip file or JAR manifest missing :
/app/opt/netlogo/lib/app/browse-fix.jar
Error occurred during initialization of VM
agent library failed to init: instrument

On top of that, browse-fix.jar was a prebuilt binary committed to the repository, so what shipped depended on the file surviving checkout, CI, and bundling intact, with no check at build time. Headless runs paid for a fix they never needed, since a batch JVM has no EDT and never opens a browser.

Two smaller problems surfaced along the way. The runtime exports JAVA_HOME=/usr/lib/jvm/java-21-openjdk, which does not exist inside the sandbox, so netlogo-headless.sh, netlogo-gui.sh, and behaviorsearch_headless.sh all failed with No such file or directory. And there was no way to reach those launchers from outside the sandbox anyway, since only the jpackage binaries were symlinked into /app/bin.

Changes

• The agent is referenced as -javaagent:$APPDIR/browse-fix.jar. jpackage expands $APPDIR to the real lib/app at launch, so the option stays valid wherever the app image is mounted: installed app, flatpak-builder build directory, flatpak build shell, or bundle.
• The agent is compiled during the build with org.freedesktop.Sdk.Extension.openjdk17, the same JDK version NetLogo bundles, and jar --list runs right after as a smoke test. A jar the JVM cannot read now fails the build instead of shipping. flatpak/browse-fix.jar is gone from version control.
• NetLogo, netlogo, NetLogo3D, and netlogo3d point at a new netlogo-launcher.sh, which picks the entry point. --headless anywhere in the arguments, or a session with neither DISPLAY nor WAYLAND_DISPLAY, goes to netlogo-headless.sh, a plain JVM with no agent. Anything else goes to the jpackage launcher, which keeps the agent, the natives path, and the rest of the packaged JVM options. The script reads its own name to decide 2D against 3D, and supplies --3D only when the caller did not.
• --env=JAVA_HOME=/app/opt/netlogo/lib/runtime in finish-args, plus a java command symlinked to the bundled runtime, so NetLogo's shell launchers and any script pointed at them find a JVM.
• behaviorsearch-headless command, since BehaviorSearch's CLI has no --headless flag to switch on.
• BrowseFix.premain returns immediately when java.awt.headless=true, so no polling thread is spawned in batch runs.

Testing

Rebuilt and reinstalled the Flatpak, then ran, all exiting 0:

• flatpak run com.danielvartan.logopak --headless --model ... --experiment ... --table ..., with a display present.
• The same through --command=netlogo in a stripped environment with no display, exercising the display check.
• --command=netlogo3d --headless on a .nlogox3d model, both with and without an explicit --3D.
• --command=netlogo --headless --3D on a 3D model, the 2D command name honoring an explicit flag.
• --command=behaviorsearch-headless, which prints its usage.

The successful headless runs are themselves proof that $APPDIR resolves, since an unresolvable agent path aborts the VM. A Swing probe inside the sandbox reports BROWSE=false without the agent and BROWSE=true with it, so the original browser fix still works, and the GUI starts with no VM init error.

Notes

• One behavior change worth knowing about: with no display and no arguments, NetLogo now prints NetLogo's batch usage message instead of an X connection error. Sessions with X forwarding set DISPLAY, so they still open the GUI.
• The build now needs the openjdk17 SDK extension. The Flathub CI image installs dependencies from Flathub, so the workflow should pick it up, but it is worth watching on the next run.

[Copilot]

Pull request overview

This PR hardens the Flatpak packaging and launch paths so the browse-fix Java agent no longer aborts headless runs, while still applying the agent for GUI launches where it’s needed. It also moves the agent from a prebuilt binary to a build-time-compiled artifact and improves launcher accessibility from outside the sandbox.

Changes:

• Add a unified netlogo-launcher.sh that routes to GUI vs. headless entrypoints (and 2D vs. 3D) based on args and display availability.
• Build browse-fix.jar during the Flatpak build using the OpenJDK 17 SDK extension, and reference it via jpackage’s $APPDIR to avoid fatal absolute-path failures.
• Rename NEWS.md → CHANGELOG.md (and update metadata), plus small documentation/spellchecker updates.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Adds a user-facing shell alias example for easier NetLogo access via Flatpak.
NEWS.md	Removes the old release notes file (replaced by CHANGELOG.md).
CHANGELOG.md	Introduces a Keep-a-Changelog-style changelog including the changes in this PR.
codemeta.json	Updates releaseNotes URL to point to CHANGELOG.md.
flatpak/com.danielvartan.logopak.yaml	Builds the agent at build time, attaches it via $APPDIR, adds launcher routing + JAVA_HOME/java exposure, and adds a BehaviorSearch headless command.
flatpak/netlogo-launcher.sh	New launcher that selects GUI vs. batch launcher and 2D vs. 3D behavior.
flatpak/BrowseFix.java	Skips patching when java.awt.headless=true to avoid unnecessary work in batch runs.
flatpak/.gitignore	Ignores locally built agent artifacts.
.vscode/settings.json	Updates cSpell dictionary for new terminology.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[danielvartan]

Ok.

[danielvartan]

Ok.