- JavaApplication
- Properties
- Methods
- Script blocks
- Property details
- Iterable applicationDefaultJvmArgs
- CopySpec applicationDistribution
- String applicationName
- The Application Plugin
- Building JVM applications
- Building applications using the Java Module System
- Building a distribution
- Customizing start script generation
- Tasks
- Application extension
- Building Java Applications Sample
- What you’ll build
- What you’ll need
- Create a project folder
- Run the init task
- Review the project files
JavaApplication
Configuration for a Java application, defining how to assemble the application.
An instance of this type is added as a project extension by the Java application plugin under the name ‘application’.
plugins < id 'application' > application < mainClass.set("com.foo.bar.FooBar") >
Properties
Array of string arguments to pass to the JVM when running the application
The specification of the contents of the distribution.
The name of the application.
Directory to place executables in
The fully qualified name of the application’s main class.
The name of the application’s Java module if it should run as a module.
Methods
Script blocks
Property details
Iterable applicationDefaultJvmArgs
Array of string arguments to pass to the JVM when running the application
CopySpec applicationDistribution
The specification of the contents of the distribution.
Use this CopySpec to include extra files/resource in the application distribution.
plugins < id 'application' > application < applicationDistribution.from("some/dir") < include "*.txt" > >
Note that the application plugin pre configures this spec to; include the contents of » src/dist «, copy the application start scripts into the » bin » directory, and copy the built jar and its dependencies into the » lib » directory.
Default value: A copy spec that includes all of the contents of src/dist , copies the start scripts into bin , and copies the built jar and all dependencies into lib
String applicationName
The name of the application.
The Application Plugin
The Application plugin facilitates creating an executable JVM application. It makes it easy to start the application locally during development, and to package the application as a TAR and/or ZIP including operating system specific start scripts.
Applying the Application plugin also implicitly applies the Java plugin. The main source set is effectively the “application”.
Applying the Application plugin also implicitly applies the Distribution plugin. A main distribution is created that packages up the application, including code dependencies and generated start scripts.
Building JVM applications
To use the application plugin, include the following in your build script:
The only mandatory configuration for the plugin is the specification of the main class (i.e. entry point) of the application.
You can run the application by executing the run task (type: JavaExec). This will compile the main source set, and launch a new JVM with its classes (along with all runtime dependencies) as the classpath and using the specified main class. You can launch the application in debug mode with gradle run —debug-jvm (see JavaExec.setDebug(boolean)).
Since Gradle 4.9, the command line arguments can be passed with —args . For example, if you want to launch the application with command line arguments foo —bar , you can use gradle run —args=»foo —bar» (see JavaExec.setArgsString(java.lang.String).
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.
If your application’s start scripts should be in a different directory than bin , you can configure the executableDir property.
Building applications using the Java Module System
Gradle supports the building of Java Modules as described in the corresponding section of the Java Library plugin documentation. Java modules can also be runnable and you can use the application plugin to run and package such a modular application. For this, you need to do two things in addition to what you do for a non-modular application.
First, you need to add a module-info.java file to describe your application module. Please refer to the Java Library plugin documentation for more details on this topic.
Second, you need to tell Gradle the name of the module you want to run in addition to the main class name like this:
That’s all. If you run your application, by executing the run task or through a generated start script, it will run as module and respect module boundaries at runtime. For example, reflective access to an internal package from another module can fail.
The configured main class is also baked into the module-info.class file of your application Jar. If you run the modular application directly using the java command, it is then sufficient to provide the module name.
You can also look at a ready made example that includes a modular application as part of a multi-project.
Building a distribution
A distribution of the application can be created, by way of the Distribution plugin (which is automatically applied). A main distribution is created with the following content:
All runtime dependencies and main source set class files.
Start scripts (generated by startScripts task).
Static files to be added to the distribution can be simply added to src/dist . More advanced customization can be done by configuring the CopySpec exposed by the main distribution.
val createDocs by tasks.registering < val docs = layout.buildDirectory.dir("docs") outputs.dir(docs) doLast < docs.get().asFile.mkdirs() docs.get().file("readme.txt").asFile.writeText("Read me!") >> distributions < main < contents < from(createDocs) < into("docs") >> > >
tasks.register('createDocs') < def docs = layout.buildDirectory.dir('docs') outputs.dir docs doLast < docs.get().asFile.mkdirs() docs.get().file('readme.txt').asFile.write('Read me!') >> distributions < main < contents < from(createDocs) < into 'docs' >> > >
By specifying that the distribution should include the task’s output files (see incremental builds), Gradle knows that the task that produces the files must be invoked before the distribution can be assembled and will take care of this for you.
You can run gradle installDist to create an image of the application in build/install/projectName . You can run gradle distZip to create a ZIP containing the distribution, gradle distTar to create an application TAR or gradle assemble to build both.
Customizing start script generation
The application plugin can generate Unix (suitable for Linux, macOS etc.) and Windows start scripts out of the box. The start scripts launch a JVM with the specified settings defined as part of the original build and runtime environment (e.g. JAVA_OPTS env var). The default script templates are based on the same scripts used to launch Gradle itself, that ship as part of a Gradle distribution.
The start scripts are completely customizable. Please refer to the documentation of CreateStartScripts for more details and customization examples.
Tasks
The Application plugin adds the following tasks to the project.
Creates OS specific scripts to run the project as a JVM application.
Depends on: jar , startScripts
Installs the application into a specified directory.
Depends on: jar , startScripts
Creates a full distribution ZIP archive including runtime libraries and OS specific scripts.
Depends on: jar , startScripts
Creates a full distribution TAR archive including runtime libraries and OS specific scripts.
Application extension
The Application Plugin adds an extension to the project, which you can use to configure its behavior. See the JavaApplication DSL documentation for more information on the properties available on the extension.
You can configure the extension via the application <> block shown earlier, for example using the following in your build script:
Building Java Applications Sample
This guide demonstrates how to create a Java application with Gradle using gradle init . You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above.
What you’ll build
You’ll generate a Java application that follows Gradle’s conventions.
What you’ll need
- A text editor or IDE — for example IntelliJ IDEA
- A Java Development Kit (JDK), version 8 or higher — for example AdoptOpenJDK
- The latest Gradle distribution
Create a project folder
Gradle comes with a built-in task, called init , that initializes a new Gradle project in an empty folder. The init task uses the (also built-in) wrapper task to create a Gradle wrapper script, gradlew .
The first step is to create a folder for the new project and change directory into it.
Run the init task
From inside the new project directory, run the init task using the following command in a terminal: gradle init . When prompted, select the 2: application project type and 3: Java as implementation language. Next you can choose the DSL for writing buildscripts — 1 : Groovy or 2: Kotlin . For the other questions, press enter to use the default values.
The output will look like this:
$ gradle init Select type of project to generate: 1: basic 2: application 3: library 4: Gradle plugin Enter selection (default: basic) [1..4] 2 Select implementation language: 1: C++ 2: Groovy 3: Java 4: Kotlin 5: Scala 6: Swift Enter selection (default: Java) [1..6] 3 Select build script DSL: 1: Groovy 2: Kotlin Enter selection (default: Groovy) [1..2] 1 Select test framework: 1: JUnit 4 2: TestNG 3: Spock 4: JUnit Jupiter Enter selection (default: JUnit 4) [1..4] Project name (default: demo): Source package (default: demo): BUILD SUCCESSFUL 2 actionable tasks: 2 executed
The init task generates the new project with the following structure:
├── gradle (1) │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew (2) ├── gradlew.bat (2) ├── settings.gradle.kts (3) └── app ├── build.gradle.kts (4) └── src ├── main │ └── java (5) │ └── demo │ └── App.java └── test └── java (6) └── demo └── AppTest.java
├── gradle (1) │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew (2) ├── gradlew.bat (2) ├── settings.gradle (3) └── app ├── build.gradle (4) └── src ├── main │ └── java (5) │ └── demo │ └── App.java └── test └── java (6) └── demo └── AppTest.java
1 | Generated folder for wrapper files |
2 | Gradle wrapper start scripts |
3 | Settings file to define build name and subprojects |
4 | Build script of app project |
5 | Default Java source folder |
6 | Default Java test source folder |
You now have the project setup to build a Java application.
Review the project files
The settings.gradle(.kts) file has two interesting lines:
rootProject.name = "demo" include("app")