This guide demonstrates how to use Gradle’s Build Init plugin to create a new Java application that follows Gradle conventions.

What you’ll need

Check the user manual

Gradle comes with a built-in plugin called the Build Init plugin. It is documented in the Gradle User Manual. The plugin provides a task, called init, that generates the project. The plugin also uses the (also built-in) wrapper task to create a Gradle wrapper script, gradlew.

Setup

The first step is to create a folder for the new project and change directory into it.

$ mkdir demo
$ cd demo

Run the init task

From inside the new project directory, run the init task and select java-application project type when prompted. For the other questions, press enter to use the default values.

$ gradle init

Select type of project to generate:
  1: basic
  2: cpp-application
  3: cpp-library
  4: groovy-application
  5: groovy-library
  6: java-application
  7: java-library
  8: kotlin-application
  9: kotlin-library
  10: scala-library
Enter selection (default: basic) [1..10] 6

Select build script DSL:
  1: groovy
  2: kotlin
Enter selection (default: groovy) [1..2]

Select test framework:
  1: junit
  2: testng
  3: spock
Enter selection (default: junit) [1..3]

Project name (default: demo):

Source package (default: demo):


BUILD SUCCESSFUL in 1s
2 actionable tasks: 2 executed

If you prefer the Kotlin DSL, you can select kotlin for the build script DSL.

The init task runs the wrapper task first, which generates the gradlew and gradlew.bat wrapper scripts. Then it creates the new project with the following structure:

├── build.gradle
├── gradle    (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   ├── java  (2)
    │   │   └── demo
    │   │       └── App.java
    │   └── resources
    └── test      (3)
        ├── java
        │   └── demo
        │       └── AppTest.java
        └── resources
├── build.gradle.kts
├── gradle    (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
    ├── main
    │   ├── java  (2)
    │   │   └── demo
    │   │       └── App.java
    │   └── resources
    └── test      (3)
        ├── java
        │   └── demo
        │       └── AppTest.java
        └── resources
1 Generated folder for wrapper files
2 Default Java source folder
3 Default Java test folder

Review the generated project files

The settings.gradle file is heavily commented, but has only one active line:

settings.gradle
rootProject.name = 'demo'
settings.gradle.kts
rootProject.name = "demo"

This sets the name of the root project to "demo", which overrides the default behavior of naming the project after the directory it’s in.

The generated build.gradle file also has many comments. The active portion is reproduced here (note version numbers for the dependencies may be updated in later versions of Gradle):

build.gradle
plugins {
    id 'java'
    id 'application'
}

repositories {
    jcenter() (1)
}

dependencies {
    implementation 'com.google.guava:guava:26.0-jre' (2)

    testImplementation 'junit:junit:4.12' (3)
}

mainClassName = 'demo.App' (4)
build.gradle.kts
plugins {
    java
    application
}

repositories {
    jcenter() (1)
}

dependencies {
    implementation("com.google.guava:guava:26.0-jre") (2)

    testImplementation("junit:junit:4.12") (3)
}

application {
    mainClassName = "demo.App" (4)
}
1 public Bintray Artifactory repository
2 Google Guava library
3 JUnit testing library
4 Class with "main" method (used by Application plugin)

The build file adds the java and application plugins. The former support Java projects. The latter lets you designate one class as having a main method, which can be executed by the build from the command line. In the demo, the name of the main class is App.

The file src/main/java/demo/App.java is shown here:

src/main/java/App.java
package demo;

public class App {
    public String getGreeting() {
        return "Hello world.";
    }

    public static void main(String[] args) {  (1)
        System.out.println(new App().getGreeting());
    }
}
1 Called by Application plugin "run" task

The test class, src/test/java/demo/AppTest.java is shown next:

src/test/java/AppTest.java
package demo;

import org.junit.Test;
import static org.junit.Assert.*;

public class AppTest {
    @Test public void testAppHasAGreeting() {
        App classUnderTest = new App();
        assertNotNull("app should have a greeting", classUnderTest.getGreeting());
    }
}

The generated test class has a single test annotated with JUnit’s @Test annotation. The test instantiates the App class, invokes the getGreeting method, and checks that the returned value is not null.

Execute the build

To build the project, run the build task. You can use the regular gradle command, but when a project includes a wrapper script, it is considered good form to use it instead.

$ ./gradlew build
> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
> Task :startScripts
> Task :distTar
> Task :distZip
> Task :assemble
> Task :compileTestJava
> Task :processTestResources NO-SOURCE
> Task :testClasses
> Task :test
> Task :check
> Task :build

BUILD SUCCESSFUL
8 actionable tasks: 8 executed
The first time you run the wrapper script, gradlew, there may be a delay while that version of gradle is downloaded and stored locally in your ~/.gradle/wrapper/dists folder.

The first time you run the build, Gradle will check whether or not you already have the Guava and JUnit libraries in your cache under your ~/.gradle directory. If not, the libraries will be downloaded and stored there. The next time you run the build, the cached versions will be used. The build task compiles the classes, runs the tests, and generates a test report.

You can view the test report by opening the HTML output file, located at build/reports/tests/test/index.html.

A sample report is shown here:

Test Summary

Run the application

Because the Gradle build used the Application plugin, you can run the application from the command line. First, use the tasks task to see what task has been added by the plugin.

$ ./gradlew tasks
:tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application

// ... many other tasks ...

The run task tells Gradle to execute the main method in the class assigned to the mainClassName property.

$ ./gradlew run
> Task :compileJava UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE

> Task :run
Hello world.

BUILD SUCCESSFUL in 0s
2 actionable tasks: 1 executed, 1 up-to-date


BUILD SUCCESSFUL

Summary

You now have a new Java project that you generated using Gradle’s build init plugin. In the process, you saw:

  • How to generate a Java application

  • How the generated build file and sample Java files are structured

  • How to run the build and view the test report

  • How to execute a Java application using the run task from the Application plugin

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/building-java-applications and we’ll get back to you.