Building and testing the installer package¶

Building the Windows installer¶

The OmegaT project uses Launch4j to create the application launcher and InnoSetup version 6 to build the installer and the package into a distribution.

Launch4j¶

Launch4j is a cross-platform tool for wrapping Java applications distributed as jars in lightweight Windows native executables. The executable can be configured to search for a certain JRE version or use a bundled one, and it’s possible to set runtime options, like the initial/max heap size.

The wrapper also provides a better user experience by using an application icon, a native pre-JRE splash screen, and a Java download page in case the appropriate JRE cannot be found.

The project is hosted at https://launch4j.sourceforge.net/

OmegaT project uses a Gradle plugin to use launch4j during the build process. The plugin we use is found at https://plugins.gradle.org/plugin/edu.sc.seis.launch4j

There is a gradle task in the launch4j group that will be automatically executed when the win task selected:

createAllExecutables

Inno Setup¶

We use Inno Setup to build an installer binary for Windows. Inno Setup is a free installer builder for Windows programs by Jordan Russell and Martijn Laan. First introduced in 1997, Inno Setup today rivals and even surpasses many commercial installers in a feature set and stability.

The Inno Setup executable binary runs on Windows but can also run on WINE and we have a docker image built with WINE and Linux.

Install InnoSetup on Windows¶

You need to prepare the InnoSetup6 installation manually to build a Windows installer package on Windows 10/11.

Follow the instructions at here to install the stable release.

You will also need to copy the unofficial language files into installed program directory. You can get the files from InnoSetup6 GitHub repository in https://github.com/jrsoftware/issrc/tree/main/Files/Languages/Unofficial

Lastly, open the control panel’s Systems property, open the Environment Variable edit dialog and add the Inno Setup folder C:\Program Files (x86)\Inno Setup6\ to the PATH environment variable.

Build windows package on Linux¶

The OmegaT CI/CD environment is on Ubuntu Linux 22.04. Gradle tasks automatically check for the existence of the iscc command, or a container execution environment where there is a nerdctl or docker command.

Gradle tasks¶

There are 6 tasks defined to assemble a Windows installer. Launching the win task will launch all 6 tasks.

winJRE
winJRE64
winNoJRE
winJRESigned
winJRE64Signed
winNoJRESigned

To build a signed executable binary installer, you need to have a signing tool and a certification in your smartcard (HSM). You should configure your key id and passphrase in $HOME/.gradle/gradle.properties. You also need to install a smartcard reader driver in your system.

A typical configuration looks like:

properties
#pkcs11engine=/usr/lib/x86_64-linux-gnu/engine-3/libpkcs11.so
pkcs11module=/usr/lib/libcrypto3PKCS.so
pkcs11cert=pkcs11:type=cert
winCodesignPassword=passphraseHere
winCodesignTimestampUrl=http://time.certum.pl/

The OmegaT gradle build script is configured to run the build process on Linux or Windows, and considers that the osslsigncode utility is installed on your system.

Because of recent changes of operation policy by certification authority consortiums, certification is now provided as a form of hardware security module (HSM) such as a smartcard, which makes it difficult to sign code in container environments.

If anyone knows of a way to certify our code in such environments, please let us know.

Building macOS installer¶

OmegaT project provides zip-packages which have a macOS framework folder structure with an application launcher binary. We use AppBundler that Sun Microsystems (currently Oracle) released for java applications on macOS.

We also use a gradle-appbundler-plugin configured to produce both an Intel-compatible launcher and an M1/M2 compatible launcher. The genMac task is used to configure the launcher generation.

Warning The zip-packages are only useable as non-notarized packages and thus not useable for distribution targetting macOS 15 and above.

See the Notes regarding the notarization of the macOS package.

build distribution¶

There are several tasks defined to assemble distributions for macOS.

basic distribution without signing¶

The armMacDistZip and macDistZip tasks are used to build the standard distribution packages. If you launch the mac task, you will get these 2 package files.

Warning The zip-packages are only useable as non-notarized packages and thus not useable for distribution targetting macOS 15 and above.

See the Notes regarding the notarization of the macOS package.

Warning The mac tasks does not fail even though the task armMacDisZip fails with Task 'armMacDistZip' not found in root project 'OmegaT' and its subprojects.

signed package¶

The OmegaT project prepares tasks to sign packages for macOS.

macSignedDistZip
armMacSignedDistZip
macStapledNotarizedDistZip
armMacStapledNotarizedDistZip

Warning The zip-packages are only useable as non-notarized packages and thus not useable for distribution targetting macOS 15 and above.

See the Notes regarding the notarization of the macOS package.

Debug mac packages¶

Use one of the following tasks to prepare the package directory structure in a build/install/ folder:

installMacArmDist
InstallMacX64Dist

Warning The installArmMacDist task errors with this message: Task 'installArmMacDist' not found in root project 'OmegaT' and its subprojects.

Warning The InstallMacDist task errors with this message: Task 'installMacDist' is ambiguous in root project 'OmegaT' and its subprojects. Candidates are: 'installMacArmDist', 'installMacArmSignedDist'.

Building the distribution with a Linux Java runtime¶

OmegaT has tasks to build a distribution with Java runtime for Linux:

linux64DistTarBz
linuxArm64DistTarBz

These tasks build a tar.bz2 distribution package that includes a JRE.

Bundled Java Runtime Environments¶

You need to put a Java Runtime package in the directory specified by the assetDir property. By default, it is the parent directory of the OmegaT project source directory.

The following packages are recognized as windows JREs:

OpenJDK17U-jre_x86-32_windows_hotspot_17.0.8.1_1.zip
OpenJDK17U-jre_x64_windows_hotspot_17.0.8.1_1.zip

The following packages are recognized as macOS JREs:

OpenJDK17U-jre_aarch64_mac_hotspot_17.0.8.1_1.tar.gz
OpenJDK17U-jre_x64_mac_hotspot_17.0.8.1_1.tar.gz

The following packages are recognized as Linux JREs:

OpenJDK17U-jre_aarch64_linux_hotspot_17.0.8.1_1.tar.gz
OpenJDK17U-jre_x64_linux_hotspot_17.0.8.1_1.tar.gz

Building Linux native packages¶

OmegaT has tasks to generate Linux native packages in “DEB” and “RPM” archive formats. We use the jpackage packaging tool which is provided by Java Development Kits. The tool was introduced in Java 14, which means the OmegaT project requires JDK 17 to build packages.

The packaging tool jpackage generates installable packages for Java applications. You can provide platform-specific packages for Linux, macOS or Windows that can be installed and launched in ways familiar to user.

jpackage bundles the java runtime used to run Gradle, but can also be run with the runtime used to compile the project that relies on the jpackage utility. For OmegaT, you need to run Gradle with JDK 17 to create packages, because the application itself is compiled with Java 11, which is not compatible with jpackage.

OmegaT uses the gradle-jpackage-plugin, which integrates the jpackage command line utility bundled in the JDK into the Gradle build tool.

You can use the following tasks to produce the packages.

linuxDebDist
linuxRpmDist

You can debug the contents of the package by running the jpackage task to produce the directory structure found in build/app-image/OmegaT/.

Directory structure¶

The directory structure inside the package is slightly different from the standard zip distributions to conform to the Linux Standard Base.

For example, the deb package has the following structure:

text
/opt/omegat-org/omegat/
                  |- bin/OmegaT   (launcher exe)
                  |- share/doc/license
                  |- lib/
                       |- app/ (*.jar)
                       |- docs/ (readme, manuals)
                       |- images/
                       |- modules/
                       |- runtime/  (JRE)
                       |- scripts/
                       libapplauncher.so
                       OmegaT.png  