Updating the bundled JRE

The GNU/Linux, MacOS, and Windows versions of Protégé are bundled with a Java Runtime Environment (JRE) so that the application is directly usable “out of the box“ without requiring users to explicitly install such a JRE on their systems. This page explains how to update the bundled JRE whenever needed.

Principle

JREs for GNU/Linux, MacOS, and Windows are to be provided as Maven artefacts, under a groupId of edu.stanford.protege and a artifactId of jre.linux, jre.os-x, and jre.win, in a custom Maven repository hosted at https://github.com/protegeproject/mvn-repo.git.

When building Protégé, and more precisely the protege-desktop project, those artefacts are fetched by Maven and their contents are included in the packages created by the Maven Assembly plugin.

Preparing the JRE artefacts

GNU/Linux and Windows JREs

Preparing the GNU/Linux and Windows JREs is simply a matter of repackaging.

1. Obtain a JRE targeting the desired operating system and the x86_64 architecture, e.g. from Adoptium.
2. Unpack the archive.
3. Move the contents of the archive (which should include directories such as bin, lib, include) to a directory named jre.
4. Create a JAR archive out of that jre directory, named jre.linux-$VERSION.jar or jre.win-$VERSION.jar (where $VERSION is the version of the JRE – with any + sign that may occur within it replaced by a _).

For example, for the GNU/Linux JRE 11.0.23+9 from Adoptium:

$ curl -L -O https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.23+9/OpenJDKU11-jre_x64_linux_hotspot_11.0.23_9.tar.gz
$ tar xf OpenJDKU11-jre_x64_linux_hotspot_11.0.23_9.tar.gz
$ mv jdk-11.0.23+9-jre jre
$ jar --create --file jre.linux-11.0.23_9.jar jre

MacOS JRE

Preparing the JRE targeting MacOS is more complicated as we need a “universal” variant of the JRE – that is, a JRE made of binaries that can be run natively both on x86_64 and arm64 Mac computers. Neither Adoptium nor any other JRE makers (as far as we know) provide such universal JREs, so we need to build our own, by combining a x86_64 JRE and a arm64 JRE together. You may refer to this blog post for more details.

Roughly, the procedure is:

1. Make sure you have the Xcode Command Line Tools installed; you need especially the lipo tool.
2. Obtain both a x86_64 and a arm64 JRE for MacOS (same version, from the same provider).
3. Unpack both JREs side by side.
4. Iterate over each file in the arm64 JRE:
   1. if the file is a Mach-O binary file, use the lipo tool to combine it with the equivalent file from the x86_64 JRE;
   2. otherwise, just keep the file as it is.
5. Place all the files resulting from the previous step under a jre directory, mimicking the original directory hierarchy.
6. Create a JAR archive out of that jre directory, named jre.os-x-$VERSION.jar.

The procedure is error-prone and therefore you should not attempt to do it by hand. Instead, use a script such as the one shown in the aforementioned blog post.

Adding the prepared JREs to the custom Maven repository

Now that the JRE packages are ready, they need to be added to the https://github.com/protegeproject/mvn-repo.git repository.

Clone that repository somewhere on your machine. We’ll assume it is cloned under $MVNREPO.

Use the Maven Install plugin to install each of the JRE packages to the cloned repository. For example, for the GNU/Linux JRE and assuming that the package prepared above is available in the current directory:

$ mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file \
      -Dfile=jre.linux-11.0.23_9.jar \
      -Dpackaging=jar \
      -DlocalRepositoryPath=$MVNREPO/releases \
      -DcreateChecksum=true \
      -DgroupId=edu.stanford.protege \
      -DartifactId=jre.linux \
      -Dversion=11.0.23_9

(Note that we are explicitly using an old version of the Maven Install plugin, as more recent versions no longer support the createChecksum option.)

Repeat the procedure for the jre.os-x and jre.win packages, then commit the changes in the mvn-repo repository and make a pull request to have your changes merged upstream.

Make Protégé use the updated JRE

Once the online mvn-repo repository has been updated, you can update the protege-desktop/pom.xml file to make sure the jre.* dependencies point to the latest versions of the JRE packages. For example for the GNU/Linux JRE:

<dependency>
    <groupId>edu.stanford.protege</groupId>
    <artifactId>jre.linux</artifactId>
    <version>11.0.23_9</version>
    <scope>runtime</scope>
</dependency>

Similarly update the jre.os-x and jre.win dependencies, then build Protégé as normal.