Guides for SE student projects »

Gradle tutorial

Gradle is a build automation tool used to automate build processes. There are many ways of integrating Gradle into a project. This tutorial uses the Gradle wrapper approach.


You use a build file (named build.gradle) to describe the project to Gradle. A build file mainly consists of plugins, tasks and properties.

  • Plugins extend the functionality of Gradle. For example, the java plugin adds support for Java projects.

  • Tasks are reusable blocks of logic. For example, the task clean simply deletes the project build directory. Tasks can be composed of, or dependent on, other tasks.

  • Properties change the behavior of tasks. For instance, mainClassName of the application plugin is a compulsory property which tells Gradle which class is the entry point to your application. As Gradle favors convention over configuration, there is not much to you need to configure if you follow the recommended directory structure.

Gradle within Intellij: an overview

The following video (from the Intellij team) gives a quick overview of various ways Gradle can be used within Intellij. A quick watch of it may be useful before diving into specific use cases explained in the subsequent sections in this page.

Adding Gradle to the project

Scenario 1: You are setting up a project in Intellij IDEA. The project already has Gradle support.

If the project comes with Gradle support, you will see a build.gradle file in your project root.

  1. Open Intellij (if you are not in the welcome screen, click File > Close Project to close the existing project first)
  2. Open the project into Intellij as follows:
    1. Click Open.
    2. Select the project directory, and click OK.
    3. If there are any further prompts, accept the defaults.
  3. After the importing of the project is complete, you will see the Gradle Toolbar in the IDEA interface e.g., look for the elephant icon (on Windows, this appears on the right-edge of the IDE window) and click it.
    Gradle icon

Scenario 2: You are adding Gradle support to an ongoing project that is already set up in Intellij IDEA. Gradle wrapper files have been provided.

  1. Add the Gradle wrapper files to the project. e.g., if they are in a separate branch, merge that branch.
  2. Close the IDEA project if it is open.
  3. Delete the .idea folder.
  4. Open/import the project again, as explained in scenario 1 above.

Scenario 3: You are adding Gradle support to an ongoing project from scratch.

  • This is a good place to start.

Using Gradle in Intellij IDEA

If the Gradle tasks don't appear in the Gradle window, click the 'refresh' button in the toolbar to reimport the Gradle project.

Intellij uses Gradle to run your application by default. If you would like to run the project in the normal way, go to File > Settings and change the following settings:
change Intellij settings to not use Gradle

Running Gradle Tasks

To run a task, locate the task in the Gradle toolbar, right-click on a task, and choose run.

Alternatively, you can type the command in the terminal.

  • On Windows: gradlew <task1> <task2> …​ e.g. gradlew clean test
  • On Mac/Linux: ./gradlew <task1> <task2> …​ e.g. ./gradlew clean test

Adding plugins

Gradle plugins are reusable units of build logic. Most common build tasks are bundled into core plugins provided by Gradle. Java, Checkstyle, and Shadow are three of plugins commonly used in Java projects. The relevant lines of the build.gradle are given below:

plugins {
    id 'java'
    id 'application'
    id 'checkstyle'
    id 'com.github.johnrengelman.shadow' version '5.1.0'

Using Gradle to do some common project activities

Cleaning the project

  • clean: Deletes the files created during the previous build tasks (e.g. files in the build folder).
    e.g. ./gradlew clean

You can use clean to prevent Gradle from skipping tasks: When running a Gradle task, Gradle will try to figure out if the task needs running at all. If Gradle determines that the output of the task will be same as the previous time, it will not run the task. For example, it will not build the JAR file again if the relevant source files have not changed since the last time the JAR file was built. If you want to force Gradle to run a task, you can combine that task with clean (e.g., ./gradlew clean shadowJar). Once the build files have been clean ed, Gradle has no way to determine if the output will be same as before, and it will have no choice but to execute the task.

Running Checkstyle

gradlew checkstyleMain checkstyleTest: runs main code and test code complies with the Checkstyle rules.


Running tests

Run the test task to run the tests in the project.


Creating JAR files

Shadow is a plugin that packages an application into an executable fat jar file if the current file is outdated.

The task shadowJar (e.g., running the command gradlew shadowJar or gradlew clean shadowJar) creates the JAR file in the build/libs folder. By default, it produces a jar file with the name in the format of {archiveBaseName}-{archiveVersion}.jar and put it in the builds/libs folder. These properties can be set in the build.gradle file.

Ensure your build.gradle file contains the correct values w.r.t. the Shadow plugin e.g., mainClassName

If you are using JavaFX, see the panel below to find what else you need to add to the build.gradle to pack JavaFX libraries into the generated JAR file.



There is no need to run these Gradle tasks manually as they are called automatically by other relevant Gradle tasks.

  • compileJava: Checks whether the project has the required dependencies to compile and run the main program, and download any missing dependencies before compiling the classes. See build.gradleallprojectsdependenciescompile for the list of dependencies required.
  • compileTestJava: Checks whether the project has the required dependencies to perform testing, and download any missing dependencies before compiling the test classes. See build.gradleallprojectsdependenciestestCompile for the list of dependencies required.

Enabling assertions

To enable assertions when executing Java code, add the following to the build.gradle file.

run {
    enableAssertions = true

Managing dependencies

Gradle can automate the management of dependencies to third-party libraries. You just need to add the dependency into the build.gradle file and Gradle will do the rest. For example, here is how the JUnit library has been added to the dependencies in the build.gradle:

dependencies {
    testImplementation group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.5.0'

For example, to add the Natty (a third-party library used for parsing natural language dates e.g., today), you simply have to add the following line to the dependencies section of the build.gradle file.

compile group: 'com.joestelmach', name: 'natty', version: '0.6'

Tip: Most third-party libraries specify how to add it as a Gradle dependency (example).



  • Initial Version: Jeffry Lum