The Application Plugin

Gradle’s Application Plugin simplifies the process of creating an executable JVM application. It provides convenient tools for running the application locally during development and for packaging it as compressed ZIP and/or TAR archives, complete with platform-specific startup scripts(.bat for Windows and .sh for Linux).

Note: Applying the Application Plugin also implicitly applies the Java Plugin and the Distribution Plugin.

The Application plugin exposes tasks (of distribution plugin) to the project:

• run - run the application
• startScripts - create .bat/.sh startup scripts to run the project as JVM app
• distZip - Creates a full distribution ZIP archive including runtime libraries and OS specific scripts
• distTar - Creates a full distribution TAR archive including runtime libraries and OS specific scripts
• installDist - Installs the application into a specified directory

Creating Distribution

1. Add the application plugin to the project. In build.gradle inside plugins block

plugins {
    id 'application'
    // other plugins
}

2. Specify the main class

application {
    mainClass = 'org.gradle.sample.Main'
}

3. Run the task distZip(or distTar):

4. Done!

This will create a .zip with the app name inside your build/distributions directory, with the following (default) structure:

\---myApp-0.0.1-SNAPSHOT
    +---bin
    |       myApp
    |       myApp.bat
    |
    \---lib
            jackson-annotations-2.15.2.jar
            log4j-api-2.20.0.jar
            ...
            logback-core-1.4.11.jar
            myApp-0.0.1-SNAPSHOT-plain.jar
            slf4j-api-2.0.7.jar
            ...

• bin - Start scripts (generated by startScripts task). For Windows(.bat) and other for Linux.
• lib - All runtime dependencies and main source set class files(a plain/flat jar of your app).

To run you app from the distribution, cd into the bin dir and run the scripts

cd  build\distributions\<APP_NAME>\bin
myApp.bat

Customizing the distribution

Configure default JVM settings

If your application requires a specific set of JVM settings or system properties, you can configure the applicationDefaultJvmArgs property. These JVM arguments are applied to the run task and also considered in the generated start scripts of your distribution.

application {
    applicationDefaultJvmArgs = ['-Dgreeting.language=en']
}

Configure start scripts location

If you want you application’s start scripts in a different directory than bin, you can configure the executableDir property. Set the custom_bin_dir relative to the default bin dir.

application {
 executableDir = ‘custom_bin_dir’
}

Note: If you choose to do this, you have to also take care of the APP_HOME. The plugin does not take of it by default.

Consider this configuration:

application {
 mainClass = 'com.example.demo.DemoApplication'
 executableDir = '../'
}

Note, the executableDir is set to ../, meaning the parent dir of bin dir.

We go to build/distribution directory and unzip the dist.zip, and run the start script. We get an error like this —

D:\codespace\demo\build\distributions\myApp-0.0.1-SNAPSHOT>myApp.bat
Error: Could not find or load main class com.example.demo.DemoApplication
Caused by: java.lang.ClassNotFoundException: com.example.demo.DemoApplication

This happened because the config puts the start scripts in the desired place but does not quite change it correctly.

To fix this, we have to set APP_HOME to correct path. We can do so by adding the code snippet to startScripts configuration. Which essentially, replace the the lines setting the APP_HOME in the start scripts.

startScripts {
 doLast {
  def windowsScriptFile = file getWindowsScript()
  def unixScriptFile = file getUnixScript()

  // Change APP_HOME to root dir in startScripts
  windowsScriptFile.text = windowsScriptFile.text.replace('set APP_HOME=%DIRNAME%..\\..', 'set APP_HOME=%DIRNAME%')
  unixScriptFile.text = unixScriptFile.text.replace('APP_HOME=$( cd "${APP_HOME:-./}../.." && pwd -P ) || exit', 'APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit')
 }
}

Now, if the paths are set correctly, the application will start as usual.