Gradle
(If you have already signed up) Read the moodle first
The Moodle pages of the course contain important information which you should read before studying these pages, including information about the aims of the project and its grading. The moodle pages also link to the most relevant parts of these pages. These pages expect you to be familiar with the contents of the moodle and can feel confusing if you do not.
Gradle is a build automation tool designed to automate project management tasks such as compiling and testing software. Gradle is primarily used for Java project development. However, there are also unofficial Python plugins that enable its use for Python project development. You may use these plugins in your coursework, but their functionality has not been tested by the course staff. That said, since Python code does not need to be compiled (and cannot be easily compiled), Gradle is somewhat unnecessarily complex for use with Python. Instead, use Poetry for Python projects.
Introduction to Gradle Configuration (for Java)
These instructions are almost a direct copy from the Software Engineering course pages.
We will create a Gradle project from scratch. Start by creating a new directory in your project repository and navigate into it.
Check if the gradle command works on your system. Note that, for example, freshman laptops may have a very old version of Gradle installed. Running the command will show which version is in use.
mluukkai@melkki:~$ gradle
Starting a Gradle Daemon (subsequent builds will be faster)
> Task :help
Welcome to Gradle 4.4.1.
If the command does not work or the version is older than 6.7, install the latest version of Gradle following the instructions here.
Start by running the command gradle:
> Task :help
Welcome to Gradle 8.6.
Directory '/Users/jezberg/Documents/teaching/tiralabra/gradletest' does not contain a Gradle build.
To create a new build in this directory, run gradle init
For more detail on the 'init' task, see https://docs.gradle.org/8.6/userguide/build_init_plugin.html
For more detail on creating a Gradle build, see https://docs.gradle.org/8.6/userguide/tutorial_using_tasks.html
To see a list of command-line options, run gradle --help
For more detail on using Gradle, see https://docs.gradle.org/8.6/userguide/command_line_interface.html
For troubleshooting, visit https://help.gradle.org
...
The output indicates that no Gradle build exists in the current directory, meaning the Gradle project has not been initialized yet.
A Gradle project is defined using a file named build.gradle in the root of the project directory.
You can create this file by running the init task (i.e., executing the command gradle init).
Next, let’s run the init command.
jezberg@LM2-500-27156 gradletest % gradle init
Select type of project to generate:
1: basic
2: application
3: library
4: Gradle plugin
Enter selection (default: basic) [1..4]
Select basic (type of project), Groovy (build script DSL), and provide a name for the project. Also, choose “no” when asked about new API features. After running the operation, you’ll notice that in addition to the build.gradle file, other files, and directories have been created in the project directory:
$ ls -la drwxr-xr-x 9 jezberg ATKK\hyad-all 288 Feb 6 17:06 . drwxr-xr-x 8 jezberg ATKK\hyad-all 256 Feb 6 16:55 .. -rw-r--r-- 1 jezberg ATKK\hyad-all 214 Feb 6 17:06 .gitattributes -rw-r--r-- 1 jezberg ATKK\hyad-all 103 Feb 6 17:06 .gitignore -rw-r--r-- 1 jezberg ATKK\hyad-all 201 Feb 6 17:06 build.gradle drwxr-xr-x 4 jezberg ATKK\hyad-all 128 Feb 6 17:06 gradle -rwxr-xr-x 1 jezberg ATKK\hyad-all 8692 Feb 6 17:06 gradlew -rw-r--r-- 1 jezberg ATKK\hyad-all 2918 Feb 6 17:06 gradlew.bat -rw-r--r-- 1 jezberg ATKK\hyad-all 345 Feb 6 17:06 settings.gradle
The directory .gradle should be added to .gitignore. In Gradle projects, the build directory should always be gitignored, as it contains all files generated by Gradle tasks. Fortunately, Gradle automatically creates an appropriate .gitignore file for this setup.
Our goal is to add Java code and JUnit tests to the project. By default, Gradle does not recognize Java, but by enabling the java-plugin, it adds new tasks related to compiling Java code.
Start by running the command gradle.
> Task :help
Welcome to Gradle 6.7.
To run a build, run gradle <task> ...
To see a list of available tasks, run gradle tasks
To see a list of command-line options, run gradle --help
To see more detail about a task, run gradle help --task <task>
For troubleshooting, visit https://help.gradle.org
...
The instructions guide us as follows:
“To see a list of available tasks, run gradle tasks.”
So, let’s try executing the command gradle tasks.
> Task :tasks
------------------------------------------------------------
Tasks runnable from root project
------------------------------------------------------------
Build Setup tasks
-----------------
init - Initializes a new Gradle build.
wrapper - Generates Gradle wrapper files.
Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'intro_gradle'.
components - Displays the components produced by root project 'intro_gradle'. [incubating]
dependencies - Displays all dependencies declared in root project 'intro_gradle'.
dependencyInsight - Displays the insight into a specific dependency in root project 'intro_gradle'.
dependentComponents - Displays the dependent components of components in root project 'intro_gradle'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'intro_gradle'. [incubating]
outgoingVariants - Displays the outgoing variants of root project 'intro_gradle'.
projects - Displays the sub-projects of root project 'intro_gradle'.
properties - Displays the properties of root project 'intro_gradle'.
tasks - Displays the tasks runnable from root project 'intro_gradle'.
The command lists the available tasks. Gradle’s documentation describes tasks as follows:
Each project is made up of one or more tasks. A task represents some atomic piece of work which a build performs. This might be compiling some classes, creating a JAR, generating Javadoc, or publishing some archives to a repository
Tasks are essentially “commands” that we can execute for Gradle projects.
Now, let’s enable the java-plugin by adding a line to the build.gradle file:
plugins {
id 'java'
}
When we now run the gradle tasks command, we will notice that there are new tasks in the list, which were added by the java-plugin:
Build tasks ----------- assemble - Assembles the outputs of this project. build - Assembles and tests this project. buildDependents - Assembles and tests this project and all projects that depend on it. buildNeeded - Assembles and tests this project and all projects it depends on. classes - Assembles main classes. clean - Deletes the build directory. jar - Assembles a jar archive containing the main classes. testClasses - Assembles test classes. Build Setup tasks ----------------- init - Initializes a new Gradle build. wrapper - Generates Gradle wrapper files. Documentation tasks ------------------- javadoc - Generates Javadoc API documentation for the main source code. ... Verification tasks ------------------ check - Runs all checks. test - Runs the unit tests.
If we execute, for example, the task build, meaning the command gradle build, the output is as follows:
BUILD SUCCESSFUL in 885ms
This doesn’t explain much yet. The documentation for the Java plugin clarifies the matter:
So, build depends on two plugins: check and assemble.
These also depend on a few tasks. In the end, gradle build executes all the following tasks:
compileJava processResources classes jar assemble compileTestJava processTestResources testClasses test check
So, build compiles the code, packages it into a JAR file, and runs the project’s tests.
Before moving forward, execute gradle clean, which removes all files created by the previous command.
A reasonable editor
This time, don’t use NetBeans. Instead, write all code and configurations using a text editor.
A good choice for an editor is Visual Studio Code, which is available on the department’s computers and freshmen laptops.
Adding Code to the Project
Gradle assumes that the program’s code is located in the directory src/main/java under the project root.
Create the necessary directory (or directories) and the file src/main/java/Main.java with the following example content:
public class Main {
public static void main(String[] args) {
System.out.println("Hello gradle!");
}
}
Then, execute the task compileJava and inspect the contents of the project directory using the command tree:
$ tree . ├── build │ ├── classes │ │ └── java │ │ └── main │ │ └── Main.class ...
Remember that Gradle commands must be executed from the project root, i.e., the directory where the build.gradle file is located.
The task compileJava has now created the build directory, containing the compiled class file.
Run the compiled code by navigating to the appropriate directory and executing the command java Main:
$ cd build/classes/java/main/ $ java Main Hello gradle!
Usually, Java code is not executed directly using class files. A better approach is to package the code into a jar file.
The jar file is created using the Gradle task jar. The help command provides the following information:
% gradle help --task jar
> Task :help
Detailed task information for jar
Path
:jar
Type
Jar (org.gradle.api.tasks.bundling.Jar)Määritellään taskia varten _pääohjelman sijainti_ lisäämällä seuraava tiedoston _build.gradle_ loppuun:
Options
--rerun Causes the task to be re-run even if up-to-date.
Description
Assembles a jar archive containing the classes of the 'main' feature.
Group
build
BUILD SUCCESSFUL in 1s
1 actionable task: 1 executed
To define the main class location for the task, add the following to the end of the build.gradle file:
jar {
manifest {
attributes 'Main-Class': 'Main'
}
}
Note that the build.gradle file must begin with the plugins definition. If it is not at the beginning, you will encounter the following error message:
FAILURE: Build failed with an exception.
* Where:
Build file '/Users/mluukkai/dev/intro_gradle/build.gradle' line: 7
...
@ line 7, column 1.
plugins {
Now, return to the project root directory and execute the task jar to generate the JAR file (i.e., run the command gradle jar).
You can run the generated JAR file as follows (note that the file name depends on your project name and is likely not gradle-test.jar):
$ java -jar build/libs/gradle-test.jar Hello gradle!
application-plugin
In principle, you can also run the code using the command gradle run.
However, this currently results in the error message:
Task ‘run’ not found in root project.
The reason is that the run task is not defined by the Java plugin but by the Application plugin.
To enable this, modify the beginning of the build.gradle file as follows:
plugins {
id 'java'
id 'application'
}
In fact, the line defining the java plugin is no longer needed since the application plugin already includes the necessary tasks.
However, running the command gradle run now results in the error:
No main class specified.
According to the plugin documentation, the main class must be specified by adding the following line to the build.gradle file:
application {
mainClass = 'Main'
}
Now, running the program using the task works:
$ gradle run > Task :compileJava UP-TO-DATE > Task :processResources NO-SOURCE > Task :classes UP-TO-DATE > Task :run Hello gradle! BUILD SUCCESSFUL in 1s
It’s best to run the program using the -q option, which suppresses Gradle’s own output:
$ gradle run -q Hello gradle!
Let’s extend the program so that it asks for the user’s name using a Scanner object:
import java.util.*;
public class Main {
public static void main(String[] args) {
Scanner scanner = new Scanner(System.in);
System.out.println("Who are you: ");
String name = scanner.nextLine();
System.out.println("Hello " + name);
}
}
If the program is packaged into a jar file (by running the gradle jar command), it will work as expected:
$ java -jar build/libs/gradle-test.jar Who are you: mluukkai Hello mluukkai
If the program is executed using Gradle’s run task, the result will be an error:
$ gradle run
Who are you:
Exception in thread "main" java.util.NoSuchElementException: No line found
at java.util.Scanner.nextLine(Scanner.java:1540)
at Main.main(Main.java:7)
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':run'.
> Process 'command '/Library/Java/JavaVirtualMachines/jdk1.11.0_101.jdk/Contents/Home/bin/java'' finished with non-zero exit value 1
The reason for this is that by default, Gradle’s run task does not attach the terminal to the input stream System.in. This can be fixed by adding the following to the build.gradle file:
run {
standardInput = System.in
}
Now the command gradle run works.
Second Class
Let’s add a class to the program that allows multiplication calculations. Place the class in the package ohtu, i.e., in the file src/main/java/ohtu/Multiplier.java.
package ohtu;
public class Multiplier {
private int value;
public Multiplier(int value) {
this.value = value;
}
public int multipliedBy(int other) {
return value * other;
}
}
Use the class from the main program. Note that since the class is in a different package than the main program, the package must be imported:
import java.util.*;
import ohtu.Multiplier;
public class Main {
public static void main(String[] args) {
Scanner scanner = new Scanner(System.in);
Multiplier three = new Multiplier(3);
System.out.println("Give a number ");
int luku = scanner.nextInt();
System.out.println("The number multiplied by three is " + three.multipliedBy(luku) );
}
}
Tests
Now, let’s create a JUnit test for the class. Gradle assumes that JUnit tests are placed under the directory src/test/java. We will place the test in the same package as the class being tested, in the file src/test/java/ohtu/MultiplierTest.java.
package ohtu;
import static org.junit.Assert.*;
import org.junit.Test;
public class MultiplierTest {
@Test
public void multiplicationWorks() {
Multiplier five = new Multiplier(5);
assertEquals(5, five.multipliedBy(1));
assertEquals(35, five.multipliedBy(7));
}
}
Let’s try running the tests with the command gradle test. As a result, we get a large number of error messages. The errors occur during the compileTestJava task, which means during the compilation of the tests:
$ gradle test
> Task :compileTestJava FAILED
/Users/mluukkai/dev/intro_gradle/src/test/java/MultiplierTest.java:3: error: package org.junit does not exist
import static org.junit.Assert.*;
^
/Users/mluukkai/dev/intro_gradle/src/test/java/MultiplierTest.java:4: error: package org.junit does not exist
import org.junit.Test;
^
/Users/mluukkai/dev/intro_gradle/src/test/java/MultiplierTest.java:8: error: cannot find symbol
@Test
^
symbol: class Test
location: class MultiplierTest
/Users/mluukkai/dev/intro_gradle/src/test/java/MultiplierTest.java:12: error: cannot find symbol
assertEquals(5, five.multipliedBy(1));
^
symbol: method assertEquals(int,int)
location: class MultiplierTest
/Users/mluukkai/dev/intro_gradle/src/test/java/MultiplierTest.java:13: error: cannot find symbol
assertEquals(35, five.multipliedBy(7));
^
symbol: method assertEquals(int,int)
location: class MultiplierTest
5 errors
The reason for the errors is that our project does not recognize the code imported by the tests:
import static org.junit.Assert.*; import org.junit.Test;
This means that the JUnit library is a dependency required during the compilation of our tests.
Dependencies
In practice, dependencies are JAR files that contain the code of external libraries — in this case, JUnit. The advantage of Gradle, like Maven, is that the developer does not need to download dependencies manually. Instead, dependencies are defined in the build.gradle file, and Gradle automatically downloads them if they are not already available on the system.
The required configuration is as follows:
repositories {
mavenCentral()
}
dependencies {
testImplementation group: 'junit', name: 'junit', version: 'latest-release'
}
The first part, repositories, tells Gradle where to look for dependencies. mavenCentral is one of the main repositories that store many libraries used by Gradle and Maven. The repositories section can define multiple locations where Gradle searches for the project’s dependencies.
The second part specifies that the latest version of the JUnit library should be used for the testImplementation phase. In practice, this means that when compiling the test code, Gradle adds JUnit to the classpath.
There is also an alternative syntax for defining dependencies, where the dependency and its version are expressed as a single string:
dependencies {
testImplementation 'junit:junit:latest-release'
}
When we run the command gradle test again, everything works correctly.
Remember to intentionally break a test and verify that the test framework detects the error.
Fix this page
Make an suggestion for an improvement by editing this file in GitHub.