What Maven is and what problem it solves

Maven is a build tool for Java projects. A build is everything between the source files and a jar somebody can run: compile the classes, run the tests, copy the resources, write the manifest, put the files together, install the result where another project can find it. Done by hand it is three commands and a list of files that everybody on the team has to keep in step. Done with Maven it is a description of the project and one command. This page builds the same two-file program both ways, so the difference is visible before any of the vocabulary arrives.

The build by hand

The two files

The program is two classes in the package com.example.manual: Calc.java holds the code, Main.java prints it. Nothing here is Maven-specific; it is the program the rest of the page builds.

src/main/java/com/example/manual/Calc.java

package com.example.manual; public class Calc { static int add(int a, int b) { return a + b; } }

src/main/java/com/example/manual/Main.java

package com.example.manual; public class Main { public static void main(String[] args) { System.out.println("Hello, Maven!"); System.out.println("1 + 2 = " + Calc.add(1, 2)); } }

Three commands

The whole build is javac into a folder of classes, jar over that folder with the class that holds main, and java -jar to run what came out. Java 21 has the jar tool with the long options, so nobody has to remember the old cfm letters:

javac -d target/classes src/main/java/com/example/manual/Calc.java src/main/java/com/example/manual/Main.java
find target -type f | sort
jar --create --file target/manual.jar --main-class com.example.manual.Main -C target/classes .
jar tf target/manual.jar | sort
java -jar target/manual.jar

target/classes/com/example/manual/Calc.class
target/classes/com/example/manual/Main.class
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/manual/
com/example/manual/Calc.class
com/example/manual/Main.class
Hello, Maven!
1 + 2 = 3

find lists the two class files and nothing else: the source tree and the output tree are separate by hand because the command says so. jar tf lists what went into the jar, and the last two lines are the program running out of that jar. javac, jar and java printed nothing, which is their way of saying that they worked.

Four things in that list are easy to get wrong, and every one of them has bitten a real project. The class path grows with every library and somebody has to remember all of it. The javac line names the files, so a new class is added to the command or it is not compiled at all. The output folder is a convention of this page; the next person uses out and the scripts disagree. And the manifest is written by an option of jar, so its contents live in a shell history rather than in the project.

The same build with Maven

The Maven version of the project is one file next to the two classes. It names the project, says which Java release to compile for, and stops there: the folders src/main/java and target are the defaults of Maven, not settings of this pom.

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>manual</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> </project>

One command builds the same jar. The log below is the whole run, and it is written by a command line that also prints the status of Maven and rewrites the folder the build runs in: every log on these pages was captured that way, so <project> is the folder on your machine. Your Total time and Finished at differ from mine.

mvn -B package > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:manual >-------------------------
[INFO] Building manual 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ manual ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ manual ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 2 source files with javac [debug release 21] to target/classes
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ manual ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ manual ---
[INFO] No sources to compile
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ manual ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ manual ---
[INFO] Building jar: <project>/target/manual-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.001 s
[INFO] Finished at: 2026-11-22T08:18:34Z
[INFO] ------------------------------------------------------------------------

The lines are worth reading once, because this course reads them for thirty pages. Maven prints the coordinates it found: com.example:manual, version 1.0.0, packaging jar. Then every step of the build is one line that names the plugin, its version and the goal: resources:3.4.0:resources, compiler:3.15.0:compile, surefire:3.5.4:test, jar:3.5.0:jar. The version numbers are the ones this image has; the lifecycle page explains where they come from.

The jar that came out has the manifest Maven wrote and two classes, and it runs with the class name rather than with -jar:

java -cp target/manual-1.0.0.jar com.example.manual.Main
jar tf target/manual-1.0.0.jar | sort

Hello, Maven!
1 + 2 = 3
META-INF/
META-INF/MANIFEST.MF
META-INF/maven/
META-INF/maven/com.example/
META-INF/maven/com.example/manual/
META-INF/maven/com.example/manual/pom.properties
META-INF/maven/com.example/manual/pom.xml
com/
com/example/
com/example/manual/
com/example/manual/Calc.class
com/example/manual/Main.class

The jar has four entries the hand-made one did not: META-INF/maven/ with the pom and its properties, which is how a jar tells the world where it came from. Nothing writes a Main-Class line into the manifest yet, so java -jar would say that the jar has no main manifest attribute; the package page adds that line with the jar plugin, and java -cp is what runs the jar until then.

What the pom does for you

The pom said three things: who the project is, which Java it targets, which encoding the sources use. Maven turned that into the four build steps, found the source folder it expects, wrote the jar under the name it derives from the artifact id and the version, and printed every step as it ran. The parts that the hand build had to remember are now defaults of the tool.

What Maven did not do is as useful to see: it did not compile a test, because there is no test, and it did not write a main class into the manifest, because the pom does not ask for one. A build tool does what the project describes and the defaults it brings; nothing is guessed from the sources.

Where to go next

The next article reads mvn -v and the settings file of this image, which is what makes every command on these pages run without a network. The archetype article then writes a whole project from a template, and the layout article explains the folders this page already used. The Java hub collects the pages about the language itself.

Article author: Arthur Isaev