Maven and Gradle: building real projects

Every program in this course so far has been a few files that you compile with javac or run with one button. A real project is bigger. It has dozens or hundreds of classes, it uses libraries that other people wrote, and it has tests that must pass before anyone ships it. A build tool takes care of all of that from one short command, the same way on every computer. This lesson works through Maven step by step, then builds the same project with Gradle. Along the way you learn to read what both of them print, especially when a build fails.

What a build tool is for#

Here is the bank account from the testing lesson, grown into a small project. The class lives in the package com.example.bank, a Mainclass uses it, and a test class checks it. The account also stores its owner's name. People type names in all sorts of ways, so the account tidies the name with a library: code that someone else wrote, tested and shared, delivered as a JAR file. One method of Apache Commons Text turns ada LOVELACE into Ada Lovelace.

The test class, BankAccountTest, has the deposit and withdraw tests from the testing lesson and one more that checks the owner's name comes out as Ada Lovelace. Try to build the program with the tools you already know. From the project folder:

javac has never heard of Commons Text. A library is not part of Java, so you fetch its JAR yourself and put it on the classpath. Download commons-text-1.15.0.jarfrom the library's website and try again:

It compiles, and then the program crashes. Read the stack trace from the top: inside Commons Text, capitalizeFully needed a class called StringUtils from a second library, Apache Commons Lang, which you never asked for. Libraries are built on other libraries. Only after you track down the right version of that one as well does the program print its line:

That was one library. The tests need JUnit, which arrives as nine JAR files of its own. Every teammate repeats the hunt, some end up with different versions, and the commands keep getting longer.

A build tool is a program that does this work for you. You describe the project once, in a file: its name, the Java version, the libraries it needs. Then one command:

• compiles every source file, keeping the program and its tests apart;
• downloads the libraries you named, plus the libraries those need, in versions that fit together;
• runs the tests, and stops if one fails;
• packs the compiled classes into a JAR;
• and does all of it the same way on your laptop, on a teammate's computer and on the server that checks every change.

Key idea

A build tool reads a description of your project and turns the source code into tested, packaged code with one command, the same way on every computer.

The standard project layout#

A build tool needs to know where your code is. Instead of telling it, you put every file where it expects to find one. Here is the bank project, laid out for Maven:

• pom.xml sits at the top and describes the project. The next section reads it line by line.
• src/main/java holds the program's own code. Inside it the folders follow the package name, as in packages and imports: com.example.bank becomes com/example/bank.
• src/test/java holds the tests, in the same package as the class they test. Because the package matches, a test can use the class's package-private members, while the test code stays out of the finished program.
• src/main/resources and src/test/resources, when you need them, hold files that are not code, such as a settings file or test data. The build copies them next to the compiled classes.

When you build, Maven writes everything it produces into a new folder, target: compiled classes, test reports, the finished JAR. You never edit anything inside it, and you never commit it, because the next build makes it again from src. That is why the .gitignore in Git and GitHub lists target/. Gradle uses the same src folders and writes its output to build instead.

Agreeing on where things go, so that nobody has to configure it, is called convention over configuration. It pays off every time you open someone else's project: the code is in src/main/java and the tests are in src/test/java, whoever wrote it.

The pom.xml: describing the project#

Maven reads one file, pom.xml. POM stands for Project Object Model, Maven's name for its description of a project. The file is written in XML, a text format where each value sits between an opening and a closing tag, such as <version>1.0-SNAPSHOT</version>, and tags can sit inside other tags. Here is the whole file for the bank project:

• The first four lines say which kind of XML this is, so editors can check the file as you type. Every pom starts this way. Copy them and leave them alone.
• modelVersion is the version of the POM format itself. It is 4.0.0 in every Maven 3 project.
• groupId, artifactId and version name the project. They are its coordinates, explained below.
• properties holds settings. maven.compiler.release set to 25 compiles the code for Java 25. project.build.sourceEncoding tells Maven to read the source files as UTF-8, so a name such as Zoë in your code survives on every computer.
• dependencies lists the libraries the project needs, one dependency block each.

Coordinates: a project's address#

Every project, yours and every library on the internet, is named by three values called its coordinates:

• groupId says who makes it. By convention it is a reversed domain name, like a package name: com.example here, org.apache.commons for Commons Text.
• artifactId is the project's own name, bank. An artifact is a file that a build produces, usually a JAR.
• version says which release. 1.0-SNAPSHOT means work in progress: a SNAPSHOT version is still changing, while a release version such as 1.15.0 never changes once it is published.

Written on one line with colons, Commons Text's coordinates are org.apache.commons:commons-text:1.15.0 and the bank project's are com.example:bank:1.0-SNAPSHOT. The JAR that Maven builds takes its name from the last two: bank-1.0-SNAPSHOT.jar.

Key idea

A groupId, an artifactId and a version make up a project's address. Give Maven a library's address, and it can find the library, download it and put it on the classpath.

Dependencies and Maven Central#

A dependency is another project that your project needs, named by its coordinates. The bank project has two, and they differ in their scope: which part of the build can use them. Commons Text has no scope line, so it gets the default, compile, which means the program needs it to compile and to run. JUnit has <scope>test</scope>: it is there only while the tests compile and run, so code in src/main/java cannot use it.

Maven downloads dependencies from Maven Central, a free public store of Java libraries at https://repo.maven.apache.org/maven2. You search it at central.sonatype.com, where every library has a page with its versions and the exact lines to paste into a pom or a Gradle file. Downloads are saved in your local repository, the folder .m2/repository in your home folder. Every project on your computer shares it, so each version of a library is downloaded once.

Here is the first mvn compile in the bank project, on a computer that has never run Maven. Most of the 200 download lines are cut; these are the ones for the two libraries:

Look at the addresses. The coordinates turn into folders: the dots of org.apache.commons become org/apache/commons, then come the artifact and the version. It is the same mirror-the-folders rule that packages follow.

Maven fetched Commons Lang without being asked. It downloaded Commons Text's own pom first (the .pom file), found Commons Lang listed there as a dependency, and fetched that too. A library you get because another library needs it is a transitive dependency. Most of the cut lines are Maven's own plugins, the pieces of Maven that do the actual work, such as the compiler plugin. They come from Maven Central as well, which is why the first build is slow and the ones after it are quick.

Seeing the whole tree#

mvn dependency:tree prints every library the project gets, and which library brought it:

Two dependencies in the pom became eleven JAR files. The +- and \- marks draw the tree: Commons Lang sits under Commons Text because Commons Text brought it in. The last word on each line is the scope. Everything under JUnit has the scope test too: a library that only the tests need brings its own libraries in only for the tests.

The lifecycle: compile, test, package#

You do not tell Maven how to build, step by step. You say how far you want to go, and Maven runs a fixed list of steps up to that point. The list is the lifecycle, and each step in it is a phase. These are the main phases, in order:

1. 1validate checks that the pom is complete and correct.
2. 2compile compiles src/main/java into target/classes.
3. 3test compiles the tests and runs them.
4. 4package packs the compiled classes into a JAR in target.
5. 5verify runs any extra checks on the package. A plain project has none.
6. 6install copies the JAR into your local repository, so other projects on your computer can depend on it.
7. 7deploy uploads the JAR to a shared repository, for other people to use.

Key idea

Asking for a phase runs every phase before it, in order. mvn package compiles the code, runs the tests, and only then builds the JAR.

Each phase's work is done by a plugin. A line such as --- compiler:3.16.0:compile (default-compile) @ bank --- reads: the compiler plugin, version 3.16.0, is running its goal (one job) called compile, for the project bank. Here is the real output of mvn package on the bank project, after one earlier build:

Read it from top to bottom and you can watch the phases go by. The lines about auto-discovered prefixes are Maven's bookkeeping about which files each download site holds; skip them.

The full lifecycle has more phases than the seven famous ones. The ones in between, such as process-resources and test-compile, do the preparation, and you rarely name them yourself.

Starting clean, and installing#

mvn clean deletes the whole target folder, so the next build starts from nothing:

clean belongs to a separate lifecycle, so it only runs when you ask for it. mvn clean package asks for both: first clean, then every phase up to package. That is the usual command when you want to be sure nothing old is left lying in target.

mvn install runs everything up to install, which copies the JAR and the pom into your local repository, under com/example/bank/1.0-SNAPSHOT. Another project on your computer can then list com.example:bank:1.0-SNAPSHOT as a dependency. deploy does the same for a shared repository on a server, which a team or a company sets up.

Running the program#

The JAR holds only your own classes: list it with jar tf target/bank-1.0-SNAPSHOT.jar and you find BankAccount.class and Main.class, and no Commons Text. So running it with plain java fails the way it did by hand:

Let the build tool start it instead, because it knows the whole classpath. Your editor's Run button does exactly that. In a terminal, Maven's Exec plugin runs a main class with the project's libraries on the classpath:

exec:java is a goal, not a phase, so nothing runs before it and it compiles nothing. Run mvn compile first, or put both in one command: mvn compile exec:java -Dexec.mainClass=com.example.bank.Main.

Reading a failed build#

A failed build prints a lot, and most of it looks the same every time. Read it in this order:

1. 1Go to the bottom. BUILD FAILURE confirms that it failed, and the line that starts Failed to execute goal names what failed: the compiler, Surefire, or the download of a dependency.
2. 2Find the first [ERROR] line above it that names a file, a test or a library. That line is the cause.
3. 3Skip the lines about -e, -X and [Help 1]. They appear under every failure and only offer more detail.

A compile error#

Someone mistyped balance as balanse in deposit:

The goal at the bottom is compiler:compile, so the mistake is in src/main/java; a mistake in a test fails at compiler:testCompile instead. The file and position appear twice: BankAccount.java:[18,19] means line 18, column 19. The message is javac's own, the cannot find symbol you met in reading errors and debugging. Maven runs javac for you, so a compile error reads the way it always did. Notice too that the tests never ran: a build that cannot compile stops at compile.

A failing test#

Next, a new rule: an account must refuse to pay out more than it holds. The test comes first, added to the end of BankAccountTest, and withdraw does not check anything yet:

The summary under Results:names the test and the line where it failed (39), followed by JUnit's message: the test expected an IllegalArgumentException and nothing was thrown. Tests run: 5, Failures: 1 is the count. A failure means an assertion did not hold; an error, counted separately, means a test crashed with an exception nobody expected. The details for every test class are saved in target/surefire-reports, as the last lines say.

1import org.junit.jupiter.api.Test;
2 
3import static org.junit.jupiter.api.Assertions.assertEquals;
4import static org.junit.jupiter.api.Assertions.assertThrows;
5 
6class BankAccount {
7    private int balance;
8 
9    BankAccount(int openingBalance) {
10        balance = openingBalance;
11    }
12 
13    void withdraw(int amount) {
14        // TODO: refuse an amount larger than the balance
15        balance = balance - amount;
16    }
17 
18    int getBalance() {
19        return balance;
20    }
21}
22 
23class BankAccountTest {
24 
25    @Test
26    void withdrawTakesFromTheBalance() {
27        BankAccount account = new BankAccount(100);
28        account.withdraw(30);
29        assertEquals(70, account.getBalance());
30    }
31 
32    @Test
33    void withdrawRefusesMoreThanTheBalance() {
34        BankAccount account = new BankAccount(100);
35        assertThrows(IllegalArgumentException.class, () -> account.withdraw(500));
36    }
37 
38    @Test
39    void withdrawingTheWholeBalanceLeavesZero() {
40        BankAccount account = new BankAccount(100);
41        account.withdraw(100);
42        assertEquals(0, account.getBalance());
43    }
44}

A dependency that cannot be found#

Last, a typo in the pom: 1.51.0 instead of 1.15.0 as the Commons Text version.

No plugin ran at all. Before the first phase starts, Maven must have every dependency, and Maven Central has no Commons Text 1.51.0. The [WARNING] line was the first sign: the pom for that version is missing. When you see Could not find artifact, check the coordinates and the version against the library's page on Maven Central. If they are right, check your internet connection, because a project's first build needs one.

The same project in Gradle#

Gradle builds the same project from the same folders. Its build files are short programs instead of XML, written in Kotlin (build.gradle.kts) or in Groovy (build.gradle). Both languages describe the same build. Kotlin has been the default for new projects since Gradle 8.2, and this page uses it; you do not need to know Kotlin to read one. Two files take the place of pom.xml:

• plugins { application }: Gradle knows nothing about Java until a plugin teaches it. The application plugin brings everything for compiling, testing and making a JAR, plus a run task for a program with a main method.
• group and version are two of the coordinates. The third, the name, is rootProject.name in settings.gradle.kts.
• repositories { mavenCentral() } says where to download from. Gradle uses Maven Central too, but only when the build file says so.
• implementation is Maven's compile scope and testImplementation is its test scope. Each dependency is one string of coordinates, group:name:version.
• testRuntimeOnly adds the JUnit Platform launcher, the part of JUnit that starts the tests. Since Gradle 9 you must list it yourself. It needs no version, because JUnit's own files tell Gradle which launcher goes with JUnit 6.1.3.
• The toolchain block compiles and runs everything with Java 25. If Gradle finds no JDK 25 on your computer, it stops and says so.
• mainClass tells the run task which class to start, and useJUnitPlatform() makes the test task run JUnit tests.

Tasks instead of phases#

Gradle has no fixed lifecycle. Its work is split into tasks, and each task names the tasks it needs done first. Ask for test and Gradle works out the rest. In a terminal, a passing build says very little:

The last line is a tip about a setting that makes later builds faster, and you can ignore it. To see the tasks, add --console=plain. This is the very first gradle test in the project, which also downloaded the libraries:

The tasks line up with Maven's phases: compileJava is compile, compileTestJava is test-compile, and test is test. NO-SOURCE means the task had nothing to work on, because there is no resources folder. Now run the same command again without changing a thing:

Every task is UP-TO-DATE. Gradle remembers what each task read and wrote, and skips a task when none of it has changed, the tests included. Change one file and only the tasks that depend on it run again. Maven skips compiling unchanged code too (the Nothing to compile lines earlier), but it runs every test on every build.

Running, and reading Gradle's failures#

The run task starts Main with the whole classpath, Commons Text included:

Here is the failing withdrawtest from before, run by Gradle. It names the test and the line, and puts JUnit's full message in a report you open in a browser:

Gradle's failures follow one pattern. Under * What went wrong: each > line explains the line above it, so the last, most indented one is the real cause. This is what you get if you leave out the junit-platform-launcher line: