Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 41 ยท Getting Started

Your First Maven Project

Generate a Maven project from an archetype, read the resulting folders, build a hello-world JAR with mvn package and understand every line of the console output.

The fastest way to see Maven work is to build something small. In this lesson you generate a project from a template called an archetype, look at what it created, build it into a JAR and run it. Then you learn to read the console output, which is the skill you use most often when a build fails.

You will type real commands into your own terminal, so those blocks are read-only here. The runnable examples are stand-ins: one model prints a project tree the way an archetype creates it, and another fills in an archetype-style template with your coordinates.

From nothing to a JAR

Generate archetype:generate makes the files.
Build mvn package compiles, tests, packs.
Run java -cp runs the class.

Three commands, one working program.

1 / 2

Generate the project

An archetype is a project template. Maven's archetype:generate goal downloads a template and fills in your names. The classic template is maven-archetype-quickstart, which creates a tiny Java program with one test.

TEXT
mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=hello \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DinteractiveMode=false

On Windows Command Prompt, put it on one line and drop the backslashes. Each -D flag sets a property for the run:

  • groupId names your organization or project family, written like a reversed domain (com.example).
  • artifactId is the name of this project and becomes the folder name (hello).
  • archetypeArtifactId and archetypeVersion choose the template.
  • interactiveMode=false stops Maven from asking questions, so the command runs straight through.

The first time you run it, Maven downloads the archetype plugin and the template into ~/.m2/repository, which can take a while. Later runs are fast, because everything is cached. See Repositories and the Local Cache.

The generated layout

Change into the new folder with cd hello. You will find something like this:

TEXT
hello/
โ”œโ”€โ”€ pom.xml
โ””โ”€โ”€ src/
    โ”œโ”€โ”€ main/
    โ”‚   โ””โ”€โ”€ java/
    โ”‚       โ””โ”€โ”€ com/example/
    โ”‚           โ””โ”€โ”€ App.java
    โ””โ”€โ”€ test/
        โ””โ”€โ”€ java/
            โ””โ”€โ”€ com/example/
                โ””โ”€โ”€ AppTest.java

Two things are worth noticing. First, the Java files sit in folders named after their package (com/example), as Java requires. Second, src/main and src/test are completely separate, so test code never ends up in your final JAR. The next lesson, The Standard Directory Layout, explains every folder.

The generated App.java is a hello-world class:

Java
package com.example;

public class App {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

The generated POM has the three coordinates you gave, a packaging of jar (the default, so it may not appear), and properties for the Java version. Templates change over time, so the Java version in the generated POM may be older than the JDK you installed. Always check it, and set it deliberately; Properties and Build Settings shows how.

Once you know the layout, you do not need an archetype at all. Creating a pom.xml and a src/main/java folder by hand gives the same result. Archetypes mostly save typing, and many developers use the project generator in their IDE or Spring Initializr instead.

Build it

From the folder that contains pom.xml, run:

TEXT
mvn package

package is a phase of the default lifecycle. Asking for it runs every earlier phase too: validate the project, compile the sources, compile the tests, run the tests, and finally build the JAR. You will study this in Lifecycles and Phases.

When it succeeds, you get a target folder:

TEXT
target/
โ”œโ”€โ”€ classes/                 compiled production classes
โ”œโ”€โ”€ test-classes/            compiled test classes
โ”œโ”€โ”€ surefire-reports/        test results
โ”œโ”€โ”€ maven-status/            bookkeeping for incremental builds
โ””โ”€โ”€ hello-1.0-SNAPSHOT.jar   the packaged project

The JAR name comes from the coordinates: <artifactId>-<version>.jar. The version 1.0-SNAPSHOT means "work in progress toward 1.0"; see Coordinates.

Run it

The JAR is a plain Java archive. Because the quickstart does not declare a main class in its manifest, you start it by naming the class on the classpath:

TEXT
java -cp target/hello-1.0-SNAPSHOT.jar com.example.App

It prints Hello World!. If you want java -jar to work, the manifest needs a Main-Class entry, which you configure in Packaging.

Reading the console output

An abbreviated successful build looks like this (the exact lines vary by Maven and plugin versions):

TEXT
[INFO] Scanning for projects...
[INFO] ------------------------< com.example:hello >-------------------------
[INFO] Building hello 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] --- resources:3.3.1:resources (default-resources) @ hello ---
[INFO] --- compiler:3.13.0:compile (default-compile) @ hello ---
[INFO] Compiling 1 source file with javac [debug release 17] to target/classes
[INFO] --- resources:3.3.1:testResources (default-testResources) @ hello ---
[INFO] --- compiler:3.13.0:testCompile (default-testCompile) @ hello ---
[INFO] --- surefire:3.2.5:test (default-test) @ hello ---
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] --- jar:3.4.1:jar (default-jar) @ hello ---
[INFO] Building jar: /home/me/hello/target/hello-1.0-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Each --- plugin:version:goal (execution-id) @ project --- line is one goal running. They appear in lifecycle order. Reading these lines tells you which step you are in when something breaks. The final line, BUILD SUCCESS or BUILD FAILURE, is the verdict. On failure, Maven prints [ERROR] lines naming the goal that failed and a short reason; scroll up to the first [ERROR], because later ones are usually consequences.

To start from scratch, run mvn clean, which deletes target/. You can combine them as mvn clean package. This is a handy habit when you suspect stale files.

Stand-in: the archetype as a template

An archetype is not magic: it is a set of template files with placeholders such as ${package} and ${artifactId}, plus rules for where to put them. The model below does the same job. It takes a groupId and artifactId, turns the package into a folder path and prints the resulting tree. It does not write to disk; the tree is printed.

Java Model an archetype generating a tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

This model skips everything the real archetype also does: it downloads the template from a repository, asks for missing values, and writes the files. Change groupId to org.acme.tools and run it again to watch the package folders follow.

The second stand-in fills a template string, the same way a real archetype replaces placeholders in App.java.

Java Fill in a template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Real archetypes use the Velocity template engine and support loops and conditions, which this one-line replacement does not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does mvn package do?

    Asking for a phase runs every earlier phase of the lifecycle too, so package validates, compiles, tests and then builds the JAR.
  2. 2. Which file name does the quickstart project produce for artifactId hello and version 1.0-SNAPSHOT?

    The JAR is named artifactId-version.jar and is written into target/.
  3. 3. A build fails with several [ERROR] lines. Where should you start reading?

    The first error usually names the failing goal and the real cause. Later errors often follow from it.
  4. 4. Why is test code kept in src/test instead of src/main?

    Maven compiles src/main into target/classes (which goes into the JAR) and src/test into target/test-classes (which does not).

Summary

  • mvn archetype:generate creates a project from a template; groupId and artifactId set the names.
  • The generated layout has a pom.xml, src/main/java and src/test/java, with package folders inside.
  • mvn package runs validate, compile, test-compile, test and jar; the result is target/<artifactId>-<version>.jar.
  • Console lines of the form --- plugin:version:goal --- show each goal as it runs; read the first [ERROR] on a failure.
  • mvn clean removes target/; the generated Java version may need updating.

Next, a closer look at every folder: The Standard Directory Layout.