Plugins, goals and help:describe
Everything a Maven build does is done by a plugin. Compiling, copying resources, running tests, writing the jar, installing it: each of those is a goal of a plugin, and the lifecycles of the previous part are the timetable that says when each goal runs. A plugin is an artifact like any other, with coordinates, a version and a jar in the local repository, which is why a project pins its versions and why an offline machine can stop at the first phase.
A plugin is a jar with goals
The compiler plugin is org.apache.maven.plugins:maven-compiler-plugin, and version 3.15.0 is a folder in the local repository like any dependency:
ls -1 ~/.m2/repository/org/apache/maven/plugins/maven-compiler-plugin/3.15.0/
_remote.repositories
maven-compiler-plugin-3.15.0.jar
maven-compiler-plugin-3.15.0.jar.sha1
maven-compiler-plugin-3.15.0.pom
maven-compiler-plugin-3.15.0.pom.sha1
Inside the jar are Java classes that implement one interface of Maven, one class per goal. The plugin's pom lists its own dependencies, which are loaded next to it when Maven runs it; that is why a plugin can fail to resolve even when its jar is there, and why the site lifecycle fails in this image.
A goal run directly
The project of the compile article, used here for one goal:
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>
</properties>
</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;
}
}
plugin:goal runs one goal and nothing else: no phase before it, no phase after it. The log says (default-cli) instead of an execution id, which is how a goal invoked from the command line is marked:
mvn -B compiler:compile > goal.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" goal.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] --- compiler:3.15.0:compile (default-cli) @ calc ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
The output of the goal is the output of the phase, because compile of the default lifecycle is this goal and one before it (the resources). That one-before-it is exactly what a direct goal skips: if this project had a resource, compiler:compile would compile against a classes folder without it.
help:describe
The help plugin describes any other plugin: its name, its coordinates, its version in this project and the goals it has. This is the compiler plugin, in this project:
mvn -B help:describe -Dplugin=compiler > describe.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" describe.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] --- help:3.6.0:describe (default-cli) @ calc ---
[INFO] org.apache.maven.plugins:maven-compiler-plugin:3.15.0
Name: Apache Maven Compiler Plugin
Description: The Compiler Plugin is used to compile the sources of your
project.
Group Id: org.apache.maven.plugins
Artifact Id: maven-compiler-plugin
Version: 3.15.0
Goal Prefix: compiler
This plugin has 3 goals:
compiler:compile
Description: Compiles application sources. By default uses the javac
compiler of the JDK used to execute Maven. This can be overwritten through
Toolchains or parameter compilerId. See also: javac Command
compiler:help
Description: Display help information on maven-compiler-plugin. Call mvn
compiler:help -Ddetail=true -Dgoal= to display parameter details.
compiler:testCompile
Description: Compiles application test sources. By default uses the javac
compiler of the JDK used to execute Maven. This can be overwritten through
Toolchains or parameter compilerId. See also: javac Command
For more information, run 'mvn help:describe [...] -Ddetail'
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
The first line after the goal line is the full coordinate with the version Maven resolved, and 3.15.0 is the version of the default binding of Maven 3.9.16, because this pom pins no compiler. Goal Prefix: compiler is the short name that a command line may use, and the list is the three goals of the plugin: compile, testCompile and help.
-Ddetail adds every parameter of every goal, with its expression and its default, which is the same information the debug log prints for the goals a build actually runs.
The prefix
compiler:compile is a shorthand. Maven resolves the prefix compiler to a plugin by looking in two groups: org.apache.maven.plugins, which is searched first, and org.codehaus.mojo. The plugin's pom declares its own prefix, and the metadata of the group maps prefixes to artifact ids; with no network, both are in the local repository, which is why a prefix works offline.
Three forms name the same goal, and the long one always works:
- compiler:compile: the prefix and the goal.
- maven-compiler-plugin:compile: the artifact id and the goal, with the version still resolved.
- org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile: the full coordinate, the version included, which is the only form that cannot resolve to another version.
A prefix that resolves to no plugin is the failure the IntelliJ article shows: Plugin not found in any plugin repository, with the artifact name Maven was looking for.
The plugins of a jar build
Nine plugins make up the three lifecycles of a jar project. The versions are the ones the effective pom of this project has, which for a pom without a pluginManagement is what Maven 3.9.16 brings:
- maven-clean-plugin 3.2.0: clean
- maven-resources-plugin 3.4.0: resources, testResources
- maven-compiler-plugin 3.15.0: compile, testCompile
- maven-surefire-plugin 3.5.4: test
- maven-jar-plugin 3.5.0: jar
- maven-install-plugin 3.1.4: install
- maven-deploy-plugin 3.1.4: deploy
- maven-site-plugin 3.12.1: site, deploy of the site lifecycle
- maven-project-info-reports-plugin: the reports a site is made of
A project adds a plugin for a goal the lifecycles do not run, and configures a plugin for a goal they do. Both happen in <build><plugins>, and both are one block with the coordinates, the version and the configuration: the compiler article configures the compiler, and the package article configures the jar.
Where to go next
Configuring the compiler plugin takes the plugin this article described and adds arguments to it, with the warnings they produce.
Article author: Arthur Isaev