Creating a Gradle Project

This page creates a Java project with Gradle and explains how the generated project is organized.

Initializing a Gradle Project

This section explains how to initialize a development project with Gradle.

Initialize the project

To develop with Gradle, prepare a project managed by Gradle. The basic steps are as follows.

1. Move to the location where the project will be created

Open a command prompt or terminal and move to a suitable directory. For example, to create the project on the desktop, run the following command.

$ cd Desktop

2. Create a project directory

In this example, create a directory named GradleApp.

$ mkdir GradleApp

3. Move into the project directory

Run the following command.

$ cd GradleApp

4. Initialize the project

This is the actual step that creates the base Gradle project.

$ gradle init --type java-application

gradle init initializes a Gradle project. The --type java-application option specifies that the project is a Java application.

Starting a Gradle Daemon (subsequent builds will be faster)

BUILD SUCCESSFUL in 10s
2 actionable tasks: 2 executed

After a short wait, the required files and directories are created.

Gradle Project Structure

Check the contents of the generated project directory. It should contain files and directories like the following.

Gradle directory

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   └── java
    │       └── App.java
    └── test
        └── java
            └── AppTest.java

.gradle directory

This directory is used by Gradle. Files generated by tasks are stored here. You rarely edit this directory directly.

gradle directory

This directory contains files used by Gradle when needed. By default, it stores the wrapper files that define the Gradle execution environment.

src directory

This is where the program files created in the project are stored. Source code files, resource files, and other project files are placed under this directory.

build.gradle

This is the main Gradle build configuration file. It describes how the project is built.

gradlew, gradlew.bat

These are Gradle wrapper commands. gradlew.bat is for Windows, and gradlew is for macOS and Linux.

settings.gradle

This file contains project-level settings.

The most important directory is src, because it contains the files used by the application being developed. The next important file is build.gradle, the build file that describes build processing. This file is written in Groovy.

src directory

Open the src directory, which contains the main development files. Its structure is as follows.

src
├── main
│   └── java
│       └── App.java
└── test
    └── java
        └── AppTest.java

The src directory contains two directories: main and test. They have the following roles.

main directory

This directory stores the files for the actual program. Inside it is a java directory for Java source code. The generated sample includes App.java.

test directory

This directory stores unit test files. It also contains a java directory, and the generated sample includes AppTest.java.

Both main and test first contain a language-name directory, and source files written in that language are placed under it. This is the basic Gradle project directory structure.

Is the src layout the same as Maven?

The directory structure may look familiar. In fact, the src layout is the same as an Apache Maven project. Maven projects also have src, with main and test under it.

Build tools were strongly influenced by Maven because Maven became a common standard for Java build tools. Gradle follows the same folder structure.

gradle init and Project Types

The gradle init command runs the init task. In Gradle, a unit of work is called a task, and the gradle command runs the specified task.

The init task creates project files and directories and initializes the directory. The --type option specifies what kind of project to initialize. As of October 2017, the following types were available.

java-application

This type creates a Java application project. By default, App.java is generated.

java-library

This type creates a Java library project. The main difference is that the sample source file is not an application main class. The generated build.gradle is also slightly different.

groovy-application

This type creates a project for developing a Groovy application. It can be considered the basic project type for Groovy development.

groovy-library

This type creates a project for developing a Groovy library. It is mostly the same as groovy-application, except for the sample code.

scala-library

This type creates a project for Scala, a language that runs on the Java Virtual Machine. At the time of writing, an application type for Scala was not provided.

basic

This is the basic type. It is the foundation for all project types and does not generate src. The build file also contains no concrete processing; only build.gradle and settings.gradle are created. If you run only gradle init without --type, this basic type is used.

pom

This type creates build.gradle based on Maven’s pom.xml.

For Java programmers, it is usually enough to know java-application and java-library.

Compile and Run

Basic operations

This section explains basic operations such as compiling, running, packaging, and cleaning the project with Gradle commands.

Compile the program

$ gradle compileJava

Compilation is provided as the compileJava task. It compiles Java source code.

Run the program

$ gradle run

A java-application project provides the run task. Running it executes the main class. By default, App.java is executed.

Package the program

$ gradle jar

The jar task packages the program into a Jar file. The generated file is stored under the libs directory in the project’s build directory.

Clean the project

$ gradle clean

When a project is built, many files are stored in the build directory. The clean task removes those files and returns the project to the state before the build.

Build and run

Move to the project directory in a command prompt or terminal, then run the following commands.

$ gradle compileJava
$ gradle run
$ gradle jar

When compiling, Gradle downloads required libraries as needed.

Download https://jcenter.bintray.com/com/google/guava/guava/22.0/guava-22.0.pom
Download https://jcenter.bintray.com/com/google/guava/guava-parent/22.0/guava-parent-22.0.pom
... omitted ...
Download https://jcenter.bintray.com/org/codehaus/mojo/animal-sniffer-annotations/1.14/animal-sniffer-annotations-1.14.jar
Download https://jcenter.bintray.com/com/google/guava/guava/22.0/guava-22.0.jar

BUILD SUCCESSFUL in 13s
1 actionable task: 1 executed

Run the project.

$ gradle run

> Task :run
Hello world.


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

Create the project’s Jar file.

$ gradle jar

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

When the project is run, Hello World. is printed. You can also check that GradleApp.jar has been created in the libs directory under build.

However, this Jar file cannot be run with java -jar GradleApp.jar because it does not contain a manifest file and is not an executable Jar. You can run it by explicitly specifying the classpath, such as java -classpath GradleApp.jar App. It is a little inconvenient, but it confirms that the generated program works.