Skip to content

Development

Jump to bottom Edit New page
Andreas Rudolph edited this page Mar 19, 2021 · 17 revisions

This page describes how to work with the source code and how to build the application for yourself.

Requirements

In order to build the application for yourself you need OpenJDK 11, which is provided by BellSoft, AdoptOpenJDK and Azul Systems.

Besides this it is recommended to use an IDE, that supports Java 11. A project for IntelliJ IDEA is provided in the project repository but an import into Netbeans and Eclipse should also be possible.

In case you don't use an IDE, you also need to install Apache Maven. Most IDE's already provide Apache Maven. Therefore a separate installation is not strictly necessary.

Windows

You should be able to compile the application on Windows systems. But the creation of application bundles (that contain the OpenJDK runtime environment) most probably won't work. Currently the easiest solution to create the application bundles on Windows systems should be a separate Linux installation in a VirtualBox or VMWare. Maybe creating the application bundles through Cygwin also works.

macOS

You should be able to compile the application on macOS systems. But in order to create an application bundle (that contains the OpenJDK runtime environment)

  • for Linux systems, you'll need to install makeself on your system.
  • for Windows systems, you'll need to install p7zip on your system. Wine is an optional requirement in order to automatically customize EXE application bundles (icons and other resources).

If you like to sign the compiled JAR files during deployment, you also need GnuPG.

The dependencies are available through Homebrew (see formulas for p7zip, makeself, gnupg, maven) and wine. They can be installed via:

brew install p7zip makeself gnupg maven wine

Linux

You should be able to compile the application on Linux systems. But in order to create an application bundle (that contains the OpenJDK runtime environment) you should install the following packages from your distribution:

  • Creating application bundles for Linux systems requires makeself.
  • Creating application bundles for Windows systems requires p7zip. Wine is an optional requirement in order to automatically customize EXE application bundles (icons and other resources).

If you like to sign the compiled JAR files during deployment, you also need GnuPG.

Your Linux distribution should provide packages for these dependencies - e.g. on Debian / Ubuntu you can install them via:

apt install makeself p7zip-full gnupg maven wine

Obtain OpenJDK for cross platform bundling

In order to create cross platform application bundles we need to obtain OpenJDK for each supported target platform. Unfortunately there is no easy solution available for this task yet. Therefore we've added some bash scripts in the folder release/src/openjdk.

  • init-linux-x86.sh downloads OpenJDK for Linux i686 and creates a OpenJDK runtime environment in the release/src/openjdk/runtime/linux-x86 folder
  • init-linux-x86-64.sh downloads OpenJDK for Linux x86_64 and creates a OpenJDK runtime environment in the release/src/openjdk/runtime/linux-x86-64 folder
  • init-macos-x86-64.sh downloads OpenJDK for macOS and creates a OpenJDK runtime environment in the release/src/openjdk/runtime/macos-x86-64 folder
  • init-windows-x86.sh downloads OpenJDK for Windows 32bit and creates a OpenJDK runtime environment in the release/src/openjdk/runtime/windows-x86 folder
  • init-windows-x86-64.sh downloads OpenJDK for Windows 64bit and creates a OpenJDK runtime environment in the release/src/openjdk/runtime/windows-x86-64 folder

These scripts only have to be executed once for each target platform. The created OpenJDK runtime environments in the release/src/openjdk/runtime folder are used for packaging during the release process.

You might run all these init scripts at once by executing the openjdk-init.sh script.

Development Tasks

Cleanup

In order to clean up the whole project folder you might start mvn-clean.sh or enter mvn clean on the command line from the root folder of the repository. IDE's like IntelliJ IDEA, Netbeans or Eclipse should also provide additional ways to execute this task.

Compilation

In order to compile the application you might start mvn-install.sh or enter mvn clean install on the command line from the root folder of the repository. IDE's like IntelliJ IDEA, Netbeans or Eclipse should also provide additional ways to execute this task.

Compiled JAR files and all dependencies are written into the release/target/modules folder.

Prepare the release

In order to prepare the application for release you might start mvn-release.sh or enter mvn -Prelease clean install on the command line from the root folder of the repository. IDE's like IntelliJ IDEA, Netbeans or Eclipse should also provide additional ways to execute this task.

This will assemble the applications for different target platforms in the release/target/Customer and release/target/Staff folder.

Create application bundles

Check the release folder for a file called .env, which should contain certain environment variables for creating, signing and notarizing application bundles. If this file does not exist, create a copy of .env.example and place your settings into the copied file.

After the release was prepared you can create the application bundles for the different target platforms by executing the following scripts in the release folder:

  • bundle-linux.sh creates the application bundles for Linux i686 & x86_64 in the release/target folder
  • bundle-macos.sh creates the application bundles for macOS in the release/target folder
  • bundle-windows.sh creates the application bundles for Windows 32bit & 64bit in the release/target folder

Sign application bundle for macOS

In order to make the application easily startable for your customers on macOS, you need to sign it with a Developer ID (see also Developer ID and Gatekeeper). You can obtain a Developer ID by participating on the Apple Developer Program, which currently costs 99 USD per year for individuals.

After you've joined the Apple Developer Program you can register the application under a certain identifier - e.g. com.mycompany.support.*. Put this identifier into the application bundle:

You might also want change the values for CFBundleName and CFBundleDisplayName in the Info.plist files.

Afterwards edit the .env in the release folder (or create a copy of .env.example) and place the name of your development certificate provided by Apple in the APPLE_CODESIGN_KEY variable, e.g.:

APPLE_CODESIGN_KEY="Developer ID Application: John Smith (1234567890)"

You can obtain the name of the certificate from the Keychain Access utility (in "Applications → Utilities").

After preparing the application for release and launching bundle-macos.sh you can sign the macOS application bundles via codesign-macos.sh. The signed application bundles are stored into the release/signed folder.

Notice: Signing the application for macOS requires a macOS system. As far as we know you can't do code signing from other operating systems.

Notarizing application bundle for macOS

The notarization process is necessary for recent macOS version (starting with Big Sur), if you're providing your application outside of the AppStore. You can find further information at:

Follow these steps in order to notarize your custom application build:

  • In the first step edit the .env in the release folder (or create a copy of .env.example) and change the following variables:

    APPLE_DEVELOPER_MAIL="[email protected]"
APPLE_DEVELOPER_PASSWORD="your-password"

    Notice: Apple requires the use of an application specific password - your global Apple-ID does not work. Therefore you need to login at https://appleid.apple.com/ and create an application specific password for use as APPLE_DEVELOPER_PASSWORD.

  • In the second step start notarize-macos-upload.sh to upload your previously created signed application bundle in the release/signed folder. The script will automatically detect available application bundles and gives you a choice.

  • After the upload has finished, you need to wait for some minutes until the uploaded application bundle was approved by Apple. You should receive an email at your APPLE_DEVELOPER_MAIL address. Alternatively you can execute notarize-macos-verify.sh to check the current state of verification.

  • If the application bundle was approved by Apple, you can finally execute notarize-macos-finish.sh. Once again this script lets you choose, which signed application bundle within release/signed is ready for finalization. The script will create the finally notarized application bundle for release within the release/notarized folder.

Add a custom footer
Add a custom sidebar
Clone this wiki locally