From 4a4fcd1a235202cdb7467214c096dd0d35e827db Mon Sep 17 00:00:00 2001
From: Nathan Glenn <garfieldnate@gmail.com>
Date: Fri, 16 Aug 2024 14:00:02 -0500
Subject: [PATCH] generate/upload standalone image

I did a lot of research trying to make jpackage work as well, which would
generate standalone apps and installers. However, it's just not possible to load
the native SML library right now due to several limitations which I've listed
in the readme.

See https://github.com/SoarGroup/Soar/issues/491.
---
 .github/workflows/build.yml | 18 ++++++++++++------
 build.gradle.kts            | 19 ++++++++++++++++---
 readme.md                   | 28 +++++++++++++++++++++++++++-
 3 files changed, 55 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2c576bf..2633eb4 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -47,11 +47,17 @@ jobs:
       - name: Jar
         run: ./gradlew jar --no-daemon
 
+      # create zip package (no jpackage for now; see README for why)
+      -   name: Runtime Zip
+          run: ./gradlew runtimeZip --no-daemon
+
       - name: Archive build artifacts
-        # Only runs if the previous steps were successful, and only uploads Ubuntu build
-        # (it's a cross-platform jar, so we only need one)
-        if: success() &&  startsWith(matrix.os, 'ubuntu-')
-        uses: actions/upload-artifact@v2
+        # Only runs if the previous steps were successful
+        if: success()
+        uses: actions/upload-artifact@v4
         with:
-          name: build-artifacts-${{ matrix.os }}
-          path: build/libs/VisualSoar.jar
+          name: image-and-jar-${{ matrix.os }}
+          path: |
+            build/libs/VisualSoar.jar
+            build/image.zip
+
diff --git a/build.gradle.kts b/build.gradle.kts
index 4467d48..e95f96e 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -7,6 +7,7 @@ version = "4.6.22"
 plugins {
   java
   application
+  id("org.beryx.runtime") version "1.13.1"
 }
 
 repositories {
@@ -31,9 +32,6 @@ tasks.withType<JavaExec> {
 }
 
 java {
-  toolchain {
-    languageVersion = JavaLanguageVersion.of(11)
-  }
   sourceCompatibility = JavaVersion.VERSION_11
   targetCompatibility = JavaVersion.VERSION_11
 }
@@ -83,6 +81,21 @@ tasks.named<Test>("test") {
   useJUnitPlatform()
 }
 
+////////////////////////////////////
+// JVM-included application build //
+////////////////////////////////////
+
+runtime {
+  launcher {
+    // Runtime plugin replaces {{}} with environment variables in generated scripts.
+    // Works for JLink but not jpackage! Therefore any generated standalone apps or installers
+    // won't be able to connect to soar unless SOAR_HOME in is in the users path already :(
+    // See readme for details.
+    jvmArgs.add("-Djava.library.path={{SOAR_HOME}}")
+  }
+}
+
+
 /////////////////////////////////////////////////////////////////
 // Generate version/datetime string to show in the application //
 /////////////////////////////////////////////////////////////////
diff --git a/readme.md b/readme.md
index 4115e19..7751336 100644
--- a/readme.md
+++ b/readme.md
@@ -9,7 +9,7 @@ To compile VisualSoar, you must put a copy of the latest version of sml.lib (fro
 The project is defined and managed via [Gradle](https://gradle.org/). Eclipse and
 IntelliJ can both use this project type.
 
-### Building
+### Building the jar for release with Soar
 
 The slim jar we distribute with Soar:
 
@@ -20,6 +20,32 @@ We will likely remove it in the future:
 
     ant build
 
+### JLink application image
+
+To use jlink to create a zip of the containing the application, a custom JRE, and appropriate start scripts:
+
+    ./gradle runtimeZip
+
+### JPackage standalone application and installer
+
+To create the standalone app for your OS:
+
+    ./gradlew jpackageImage
+
+To create an installer for your OS:
+
+    ./gradlew jpackageImage
+
+Unfortunately, these are not able to connect with Soar unless the user has placed the SOAR_HOME on their
+system `path`. This is due to a confluence of missing features:
+
+* To load the SML native library, Soar's Java bindings call `System.loadLibrary(name)`, which requires the library to be in `java.library.path`. This is called in a static block in the `sml` package, and I'm not sure how to mock that out.
+* Java doesn't allow modifying the library path at runtime
+* JPackage doesn't support using environment variables to form JVM arguments.
+  * Also, it's not straightforward to load the user's environment variables in a standalone application; on Mac, for example, running a .app file doesn't run my .bash_profile first, etc.
+
+I intend to revisit this after fixing the first point above in Soar: https://github.com/SoarGroup/Soar/issues/491..
+
 ### Running
 
 At runtime you need to have your SOAR_HOME environment variable set to the path to Soar's `bin/` directory.