If we want to execute a Java executable from a Gradle build, we have several options. Before we explore these options, we will first create a new Java class with a
main() method in our project. We will execute this Java class from our build file.
In the directory src/main/java/gradle/sample, we need to create a new file SampleApp.java. The following code listing shows the contents of the file. We use our Sample class to print the value of the getWelcomeMessage() method to System.out:
// File: src/main/java/gradle/sample/SampleApp.java
package gradle.sample;
import java.util.ResourceBundle;
public class SampleApp {
public SampleApp() {
}
public static void main(final String[] arguments) {
final SampleApp app = new SampleApp();
app.welcomeMessage();
}
public void welcomeMessage() {
final String welcomeMessage = readMessage();
showMessage(welcomeMessage);
}
private String readMessage() {
final Sample sample = new Sample();
final String message = sample.getWelcomeMessage();
return message;
}
private void showMessage(final String message) {
System.out.println(message);
}
}To run our SampleApp class we can use the
javaexec() method that is part of Gradle's Project class. We could also use the JavaExec task in our build file. Finally, we could use the application plugin to run our SampleApp class.
The Project class that is always available in our build file has the javaexec() method. With this method we can execute a Java class. The method accepts a closure that is used to configure the org.gradle.process.JavaExecSpec object. JavaExecSpec has several methods and properties we can use to configure the main class that needs to be executed, optional arguments, and system properties. A lot of the options are the same as for running tests.
We create a new build file and use the javaexec() method to run our SampleApp class with some extra options:
apply plugin: 'java'
task runJava(dependsOn: classes) << {
javaexec {
// Java main class to execute.
main = 'gradle.sample.SampleApp'
// We need to set the classpath.
classpath sourceSets.main.runtimeClasspath
// Extra options can be set.
maxHeapSize = '128m'
systemProperty 'sysProp', 'notUsed'
jvmArgs '-client'
}
}
runJava.description = 'Run gradle.sample.SampleApp'To run our Java class, we execute the runJava task from the command line and get the following output:
$ gradle runJava :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :runJava Welcome to Gradle. BUILD SUCCESSFUL Total time: 1.465 secs
Besides the javaexec() method, we can define a new task of type org.gradle.api.tasks.JavaExec. To configure the task, we can use the same methods and properties as with the javaexec() method.
In the following sample build file, we create the task runJava of type JavaExec. We configure the task to set the classpath and main class. Also, we see how we can add other properties and invoke other methods to further configure the execution of the Java class:
apply plugin: 'java'
task runJava(type: JavaExec) {
dependsOn classes
description = 'Run gradle.sample.SampleApp'
// Java main class to execute.
main = 'gradle.sample.SampleApp'
// We need to set the classpath.
classpath sourceSets.main.runtimeClasspath
// Extra options can be set.
systemProperty 'sysProp', 'notUsed'
jvmArgs '-client'
// We can pass arguments to the main() method
// of gradle.sample.SampleApp.
args 'mainMethodArgument', 'notUsed'
}If we run the task we get the following output:
$ gradle runJava :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :runJava Welcome to Gradle. BUILD SUCCESSFUL Total time: 0.932 secs
Another way to run a Java application is with the application plugin. The application plugin adds functionality to our build file to run Java applications and also to bundle the Java application for distribution.
To use the application plugin, we must add the plugin to our build file with the apply() method. Once we have added the plugin, we can set the main class to be executed with the property mainClassName. This time, we don't have to create a new task ourselves. The plugin has added the run task that we can invoke to run the Java application.
The sample build file uses the application plugin to run our SampleApp class:
apply plugin: 'java'
apply plugin: 'application'
mainClassName = 'gradle.sample.SampleApp'
// Extra configuration for run task if needed.
run {
// Extra options can be set.
systemProperty 'sysProp', 'notUsed'
jvmArgs '-client'
// We can pass arguments to the main() method
// of gradle.sample.SampleApp.
args 'mainMethodArgument', 'notUsed'
}We can invoke the run task and see the output of the SampleApp class:
$ gradle run :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :run Welcome to Gradle. BUILD SUCCESSFUL Total time: 1.423 secs
Note that we don't have to set the classpath property anymore. The plugin automatically includes the runtimeClasspath object of the project to execute the Java class.
With the application plugin we can also build a distribution with our Java application. This means we can distribute the application and people can run the Java application without Gradle. The plugin will create the necessary operating system-specific start scripts and package all necessary classes and dependencies.
The following table shows the extra tasks we can use with the application plugin to build a distribution:
|
Task |
Depends on |
Type |
Description |
|---|---|---|---|
|
|
|
Creates operating system-specific scripts to run the Java application. | |
|
|
|
Installs the application into a directory. | |
|
|
|
Creates a full distribution ZIP archive including all necessary files to run the Java application. |
All tasks depend on the jar task. In order to get a meaningful JAR filename, we set the properties archivesBaseName and version in our build file:
apply plugin: 'java' apply plugin: 'application' archivesBaseName = 'gradle-sample' version = '1.0' mainClassName = 'gradle.sample.SampleApp'
To create the start scripts, we invoke the createScript task. After we have executed the task, we have two files, sample and sample.bat, in the directory build/scripts. The sample.bat file is for the Windows operating system and sample is for other operating systems, such as Linux or OS X.
To have all files that are needed for running the application in a separate directory, we must run the installApp task. When we execute the task, we get a sample directory in the build/install directory. The sample directory has a bin directory with the start scripts and a lib directory with the JAR file containing the SampleApp application. We can change to the build/install/sample directory and then invoke bin/sample or bin/sample.bat to run our application:
$ gradle installApp :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar UP-TO-DATE :startScripts UP-TO-DATE :installApp BUILD SUCCESSFUL Total time: 1.511 secs $ cd build/install/sample $ bin/sample Welcome to Gradle.
To create a ZIP archive with all necessary files, which would enable others to run the application, we run the distZip task. The resulting ZIP archive can be found in the directory build/distributions. We can distribute this ZIP file and people can unzip the archive on their computers to run the Java application:
$ gradle distZip :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar UP-TO-DATE :startScripts UP-TO-DATE :distZip BUILD SUCCESSFUL Total time: 1.089 secs $ jar tvf build/distributions/sample-1.0.zip 0 Mon Apr 30 08:08:10 CEST 2012 sample-1.0/ 0 Mon Apr 30 08:08:10 CEST 2012 sample-1.0/lib/ 1890 Mon Apr 30 08:01:12 CEST 2012 sample-1.0/lib/gradle-sample-1.0.jar 0 Mon Apr 30 08:08:10 CEST 2012 sample-1.0/bin/ 4997 Mon Apr 30 08:01:14 CEST 2012 sample-1.0/bin/sample 2347 Mon Apr 30 08:01:14 CEST 2012 sample-1.0/bin/sample.bat
If we want to add other files to the distribution, we can create the directory src/dist and place files in there. Any files in the src/dist directory are included in the distribution ZIP archive. To include files from another directory, we can use the applicationDistribution copy specification.
The following sample build file uses the applicationDistribution copy specification to include the output of the docs task. Gradle will automatically execute the docs task before invoking the distZip task:
apply plugin: 'java'
apply plugin: 'application'
apply plugin: 'idea'
archivesBaseName = 'gradle-sample'
version = '1.0'
mainClassName = 'gradle.sample.SampleApp'
task docs {
def docsDir = 'docs'
def docsResultDir = file("$buildDir/$docsDir")
// Assign directory to task outputs.
outputs.dir docResultDir
doLast {
docsResultDir.mkdirs()
new File(docsResultDir, 'README').write('Please read me.')
}
}
applicationDistribution.from(docs) {
// Directory in distribution ZIP archive.
into 'docs'
}