Package, install and run the jar

package is the phase that turns a project into one file. It runs every phase before it, tests included, and then the jar plugin zips the compiled classes and writes a manifest. The result is a jar that runs from the command line, and the install phase after it copies the same jar into the local repository, where the next project can find it. This article does both and runs the jar twice: once the way a jar without a main class fails, and once after the manifest names one.

The project

The pom of the previous pages, with one class that has a main method and one test. There is no build section yet.

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>calc</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> <junit.version>5.14.3</junit.version> </properties> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> </project>

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

package com.example.calc; public class Calc { public static int add(int a, int b) { return a + b; } public static void main(String[] args) { System.out.println("1 + 2 = " + add(1, 2)); } }

src/test/java/com/example/calc/CalcTest.java

package com.example.calc; import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; class CalcTest { @Test void addsTwoNumbers() { assertEquals(4, Calc.add(1, 3)); } }

mvn package

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:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ calc ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/test-classes
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ calc ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.calc.CalcTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: <TIME> s -- in com.example.calc.CalcTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ calc ---
[INFO] Building jar: <project>/target/calc-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

The last goal is jar:3.5.0:jar (default-jar) and it prints the path of what it wrote. The jar is named after the artifact id and the version, and it sits next to the classes folder it was made from:

java -cp target/calc-1.0.0.jar com.example.calc.Calc

1 + 2 = 3

java -cp takes the jar as the class path and the fully qualified class name as the program. That works because the jar holds the class; it says nothing about which class is the program, which is what a manifest is for. Without that line, java -jar cannot know where to start:

java -jar target/calc-1.0.0.jar

no main manifest attribute, in target/calc-1.0.0.jar

The jar and its manifest

Every jar has a manifest, and Maven writes one with the tool that made it:

unzip -p target/calc-1.0.0.jar META-INF/MANIFEST.MF

Manifest-Version: 1.0
Created-By: Maven JAR Plugin 3.5.0
Java-Version: 21
Build-Jdk-Spec: 21

Main-Class is the line java -jar reads and there is none. Created-By, Java-Version and Build-Jdk-Spec are written by the jar plugin, and they are the reason two builds of the same source on two machines are not byte-identical jars.

A main class in the manifest

The jar plugin takes the main class as configuration: <archive><manifest><mainClass>. The plugin is already part of the lifecycle, so the pom does not add a phase: it configures the version it pins and the class the manifest names. The whole pom, with that block at the end:

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>calc</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> <junit.version>5.14.3</junit.version> </properties> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.5.0</version> <configuration> <archive> <manifest> <mainClass>com.example.calc.Calc</mainClass> </manifest> </archive> </configuration> </plugin> </plugins> </build> </project>

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

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ calc ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.calc.CalcTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: <TIME> s -- in com.example.calc.CalcTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ calc ---
[INFO] Building jar: <project>/target/calc-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

The tests ran again, the jar was rebuilt, and now the manifest has the line. The same two commands as before prove it, and the failure is gone:

java -jar target/calc-1.0.0.jar

1 + 2 = 3

mvn install

install is the phase after verify: it runs the same build and then copies the pom and the jar into the local repository, under the path the coordinates make.

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

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ calc ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.calc.CalcTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: <TIME> s -- in com.example.calc.CalcTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ calc ---
[INFO]
[INFO] --- install:3.1.4:install (default-install) @ calc ---
[INFO] Installing <project>/pom.xml to <HOME>/.m2/repository/com/example/calc/1.0.0/calc-1.0.0.pom
[INFO] Installing <project>/target/calc-1.0.0.jar to <HOME>/.m2/repository/com/example/calc/1.0.0/calc-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

ls -1 ~/.m2/repository/com/example/calc/1.0.0/

_remote.repositories
calc-1.0.0.jar
calc-1.0.0.pom

Two files and a bookkeeping file, and the second project that needs com.example:calc:1.0.0 gets the jar from there without building anything. The article on projects that use each other does exactly that. The jar itself does not contain the JUnit jar it was tested with: a test dependency is not packaged, and neither is any other dependency, which is why a jar with a dependency needs a class path or a fat jar; the fat jar article shows what this image cannot build.

Where to go next

The switches article shows how to package without the tests, how to run one test, and what -q and -X do to the log this page read.

Article author: Arthur Isaev