Gradle Application Plugin
External
Internal
Overview
The application plugin facilitates creating an executable JVM application. It bundles all application JARS, transitive dependencies and operating system specific scripts, custom files from project file structure, and it also generates the bash and Windows wrapper scripts to run the application with, then packages all these into a TAR or ZIP file. The plugin also allows executing the application from the project's work area with the "run" task. Note the the bundling of the project artifacts is done by the Distribution Plugin.
Concepts
Distribution
Relationship between the Application and Distribution Plugin
TODO
Typical Setup
This setup describes configuration of a multi-project build, whose sub-project create various components of the application and the top level project bundles all those in a distributable artifact. The dependencies between the sub-projects must be configured in the corresponding build.gradle files. To build the application artifact, we assume that there's a sub-project that contains the "main()" static method that triggers the execution, that method exists in "io.example.Main" class, and the sub-project in question is named "main".
As such, the top-level project build.gradle should contain the following relevant configuration:
...
apply plugin: 'application'
mainClassName = "io.example.Main"
dependencies {
...
implementation project(':main')
}
Provided that the rest of the dependencies between sub-projects are correctly declared in the corresponding build.gradle files, the execution of:
gradle distZip
will compile everything and will create a ./build/distributions/<rootProject.name>.zip file. The file includes the sub-project artifacts, their transitive dependencies, and wrapper scripts for bash and Windows.
Note that the "build" task depends on "distZip", so:
gradle build
implies "gradle distZip"
For more details about rootProject.name, see:
Properties
mainClassName
mainClassName = 'greeter.Greeter'
Building Custom Files with the Distribution
Executing the Application from Project Work Area
gradle run
The tasks executes the class specified with mainClassName property.
However, if the application requires command line parameters, they are not propagated. An alternative solution is to deploy the application ZIP file in a temporary area and execute the Application plugin-generates scripts. This is an example of a ./bin/build-and-deploy script:
Start Script Customization
This section explains the mechanics behind creating the application start (wrapper) script and shows how the process can be customized: use a different template, create multiple scripts, etc.
Start Script Mechanics
The Application plugin generates by default Unix and Windows start scripts that are capable launching a configured "main" class in an environment where the classpath is correctly set. The default script templates are based on the same scripts used to launch Gradle, which ship as part of the Gradle distribution. The start scripts are completely customizable though, as described in the Configure the Start Script Template section. The Application plugin adds a task named "startScripts" to the project's task list. The task can be view with:
gradle tasks --all
The "startScripts" task is a CreateStartScripts type task. The actual script generation is implemented in ScriptGenerator instances, returned by CreateStartScripts.getUnixStartScriptGenerator() and CreateStartScripts.getWindowsStartScriptGenerator(). The default generators are of the type TemplateBasedScriptGenerator with default templates. These templates can be changed via the TemplateBasedScriptGenerator.setTemplate(org.gradle.api.resources.TextResource) method.
Configure the Default 'startScripts' Task
Get a reference to the "startScript" task as described in Get the Reference of a Task by Name and then reconfigure state as needed:
def t = rootProject.tasks.getByPath('startScripts')
t.applicationName = 'some-app-name'
t.mainClassName = 'com.example.Main'
The following variables can be configured:
- applicationName - this will be the name of the script, without (for Linux) and with .bat extension (for Windows).
- mainClassName
- outputDir file('build/sample')
- classpath files('path/to/some.jar')
- optsEnvironmentVar
- exitEnvironmentVar
- defaultJvmOpts
- appNameSystemProperty
- appHomeRelativePath
Generate Multiple Start Scripts
We generate multiple start script by using the default "startScript" to create the main start script (or if there's no main, one of the start scripts), and we declare a new CreateStartScripts task instance for each additional script. We use the default "startScript" to read common configuration from, and we make it to depend on all newly added tasks, so they are executed automatically:
...
apply plugin: 'application'
//
// this generates an additional (not main) wrapper script
//
task secondaryStartScript(type: CreateStartScripts) {
applicationName = 'secondary'
mainClassName = 'com.example.secondary.Main'
//
// get the rest of the configuration from the already configured 'startScripts' task;
// except 'applicationName' and 'mainClassName', the rest of the configuration should
// be similar
//
def t = rootProject.tasks.getByPath('startScripts');
classpath = t.classpath;
outputDir = t.outputDir;
}
//
// this configures the main 'startScript' task to generate the "main" script
//
def t = rootProject.tasks.getByPath('startScripts')
t.applicationName = 'primary'
t.mainClassName = 'com.example.primary.Main'
t.dependsOn(secondaryStartScript) // trigger 'secondaryStartScript' execution automatically
Configure the Start Script Template
The Gradle Application Plugin builds the wrapper scripts from built-in templates. That can be changed as described in Start Script Template Configuration Process section below.
Template Specification
The default implementations used by Gradle Application CreateStartScripts use Groovy's SimpleTemplateEngine to parse the template. The following variables can be used:
- 'applicationName'
- 'optsEnvironmentVar'
- 'exitEnvironmentVar'
- 'mainClassName'
- 'executableDir'
- 'defaultJvmOpts'
- 'appNameSystemProperty'
- 'appHomeRelativePath'
- 'classpath'. Note that 'classpath' is replaced with a path that relies on "$APP_HOME":
$APP_HOME/lib/example.jar:$APP_HOME/lib/log4j.jar
Start Script Template Configuration Process
1. Get the Template. Copy the wrapper script template to be used in ./src/main/templates and name it "gradle-application-plugin-script-template".
An example of such template, that offloads functionality to an external library, so that library must be included as well, is https://github.com/ovidiuf/templates/blob/master/gradle-application-plugin-script-template
2. Get the Supporting Libraries. Copy the supporting libraries in ./src/main/dist/bin. If gradle-application-plugin-script-template is used, we need https://github.com/ovidiuf/templates/blob/master/bash.shlib, so copy that file in ./src/main/dist/bin.
3. Update the Default startScript Task.
Example:
def startScriptTemplate = './src/main/templates/gradle-application-plugin-script-template'
def t = rootProject.tasks.getByPath('startScripts')
t.applicationName = 'server'
t.mainClassName = 'io.example.server.Main'
t.unixStartScriptGenerator.template = resources.text.fromFile(startScriptTemplate)
//t.windowsStartScriptGenerator.template = resources.text.fromFile('customWindowsStartScript.txt');
4. Update any Additional startScript Tasks.
task secondaryStartScript(type: CreateStartScripts) {
applicationName = 'client'
mainClassName = 'io.example.client.Main'
//
// get the rest of the configuration from the already configured 'startScripts' task;
// except 'applicationName' and 'mainClassName', the rest of the configuration should
// be similar
//
def t = rootProject.tasks.getByPath('startScripts')
classpath = t.classpath
outputDir = t.outputDir
unixStartScriptGenerator.template = resources.text.fromFile(startScriptTemplate)
//t.windowsStartScriptGenerator.template = resources.text.fromFile('customWindowsStartScript.txt');
}