Maven Build Lifecycle

Maven has three built-in lifecycles, defined in Maven itself (not in any plugin):

Source: Maven guide: Build Lifecycle Basics

A phase is a named stage in a lifecycle. A phase does nothing by itself: it is a slot. A goal (a Mojo, "Maven plain Old Java Object") is one task implemented by a plugin, for example compiler:compile. The work happens because goals are bound to phases. When you ask for a phase, Maven runs every earlier phase of the same lifecycle in order, and in each phase it runs the goals bound to it, in the order they are declared. A phase with no goal bound to it is skipped. A goal can be bound to several phases (the compiler plugin’s compile goal is one binding, testCompile another), and a goal bound to no phase can only be run by naming it on the command line.

Source: Maven guide: A Build Phase is Made Up of Plugin Goals

The consequence for the command line is that you name the last phase you want and Maven does the rest. To get the JAR run mvn package; to run the tests run mvn test; if you are not sure, the guide recommends mvn verify, which also runs integration tests and any quality checks bound after them. A CI server that publishes typically runs mvn clean deploy.

The default lifecycle has these phases, in this order. The right-hand column says what the phase is for; which goals do the work depends on the packaging (next section).

Source: Maven guide: Lifecycle Reference

Source: Maven core reference: default lifecycle

The figure shows the same list with the goals that the jar packaging binds, plus the two small lifecycles. It is drawn from the output printed by Maven itself, shown next.

The bindings are not hidden configuration to be memorised. The Help plugin prints them for the project in the current directory, so you can always ask the Maven you are actually running. In tidepool-model (packaging jar):

(The surrounding [INFO] banner lines were removed.) Eight of the 23 phases have a goal. The other 15 exist so that plugins you add, such as the Failsafe plugin in integration-test, have a place to attach. -Dcmd accepts a phase (deploy, compile), a prefix:goal, or a prefix:goal with a version; for the clean and site lifecycles it lists that lifecycle instead:

Source: Help plugin: help:describe

Running the whole lifecycle up to verify on one module (output filtered to the lines that show which goal ran in which phase, plus the test summary; the full log is longer):

Read each --- plugin:version:goal (execution-id) @ project --- line as "this goal, from this plugin version, runs now, under this execution id, for this module". The order is the lifecycle order: clean first (it is in a different lifecycle and was named first), then the default lifecycle phases up to verify. There is no line for validate, initialize or verify because nothing is bound there. On the whole tidepool reactor the same sequence repeats for each module, in dependency order (tidepool-model, then tidepool-engine, then tidepool-cli; the parent has pom packaging and only has install and deploy, see below).

Source: Maven guide: Usual Command Line Calls

What happens in each phase is decided by the project’s <packaging>. The packaging is a named lifecycle mapping: it says which goals to bind to which phases. This is why a war project, a pom project and a plain jar all use the same mvn verify command and still do different work. The listings below are the lines of help:describe -Dcmd=deploy that are not Not defined, run in a minimal POM of each packaging on Maven 3.10.0 (the Not defined lines were removed with grep -v).

You can mix phases and goals on one command line. They run left to right, and a phase runs all earlier phases of its lifecycle first. The guide’s example, on tidepool-model (output filtered):

clean (and its predecessors in the clean lifecycle) ran first, then the goal, then package pulled in everything it depends on in the default lifecycle. The goal ran before resources and compile: only a phase drags its predecessors along, a goal runs exactly where you put it. dependency:3.11.0 was not pinned in the POM, so Maven picked the latest release it found (see prefix resolution in Plugins & Their Configuration).

A goal on its own (no phase) runs without the lifecycle at all, which is why mvn compiler:compile on a project whose resources were never copied compiles only; mvn surefire:test runs the tests against whatever is already in target/ and does not compile first:

A mistyped phase is rejected with the list of valid ones (the Available lifecycle phases list below is what Maven 3.10.0 printed, re-wrapped here):

Source: Maven guide: A Build Phase is Made Up of Plugin Goals

The guide says that phases with hyphenated names beginning pre-, post- or process- are normally not called from the command line: they sequence the build and produce intermediate results that are not useful on their own. The one that causes real trouble is integration-test. Code coverage agents and container plugins (Tomcat, Cargo, Docker) bind goals to pre-integration-test to start the environment and to post-integration-test to stop it; the verdict on the test results is delivered later, in verify. If you stop at integration-test the environment may be left running, and, as the next example shows, a failed integration test does not fail the build.

The tidepool integration tests use the Failsafe plugin (see Integration Testing with Failsafe), which binds two goals: failsafe:integration-test runs the tests but only records the result, and failsafe:verify reads the result and fails the build. A scratch module contains a deliberately failing HeightIT test. First stopping at integration-test (output filtered):

BUILD SUCCESS with a failed test. Now mvn -B verify on the same module:

This is the reason for the guide’s advice: end with verify, never with integration-test, and never call integration-test in a build that you rely on to gate a release. Also note the order in this output: the jar goal ran before integration-test, because the integration tests need the packaged artifact, and the surefire unit tests ran before jar.

Source: Maven guide: Some Phases Are Not Usually Called From the Command Line

Every execution of a goal has an execution id, and the id is the handle by which a POM can configure that one execution. Two ids are generated for you:

Because the ids are fixed, you can give the implied execution its own configuration without declaring a new execution:

The plugin-level <configuration> applies to every execution of the plugin; the default-cli block applies only when you type mvn compiler:compile. Running mvn -B -X compile compiler:compile (debug output, filtered to the configuration lines of the two compiler executions) proves it:

The lifecycle’s default-compile got the plugin-level showWarnings only; the command-line execution got both. To configure the lifecycle execution itself, give an <execution> the id default-compile. For how plugin-level and execution-level configuration merge, see Plugins & Their Configuration.

Source: Maven guide: Default executionIds for Implied Executions

To add work to the build, declare an execution with a <phase> and one or more <goals>. Goals of the same phase run in this order: those from the packaging first, then yours in the order you declare them (inherited ones from the parent come before the child’s). A scratch module tidepool-exec-demo adds three things to the plain jar build:

The first execution binds resources:copy-resources (not bound by the packaging) to generate-resources, to copy data/stations.csv into the classes. The second declares an execution with no <phase>: jar:test-jar has a default phase (package), so it runs there, after default-jar. The third rebinds the implied default-install execution to the phase none, which unbinds it. mvn -B install then shows (filtered):

copy-stations ran at generate-resources, before the packaging’s own default-resources; test-classes-jar ran after default-jar; and there is no install line although the command asked for install. Using <phase>none</phase> on a default execution id is the supported way to switch off a goal that a packaging binds (for example to skip deploy for one module of a reactor).

A goal that is not bound to any phase and has no default phase is not run by the lifecycle at all: giving it an <execution> without a <phase> has no effect. Declaring the same plugin twice in <plugins> is not the way to get two executions; use two <execution> elements. On Maven 3.10.0 a duplicate declaration is an error (see Plugins & Their Configuration).

Source: Maven guide: Using the executions tag

mvn clean runs the clean lifecycle up to clean, which runs clean:clean and deletes target/ (the earlier build’s Deleting /work/lifecycle/tidepool-model/target line). The clean lifecycle is separate from the default one, so mvn package alone never cleans: that is why people write mvn clean package.

The site lifecycle builds the web site from the <reporting> section and the src/site content. mvn site on a scratch project with the project-info reports configured (the Site plugin pinned to 3.22.0 in the POM; output filtered):

(The dependencies report was skipped because that scratch project has no dependencies.) site-deploy is the phase that publishes the generated site, bound to site:deploy. Both the site and the clean lifecycles are independent of the default one, so a build can combine them: mvn clean verify site.

Maven 3.10.0 added a switch, maven.site.lifecycle.disabled, for builds that never generate a site. With -Dmaven.site.lifecycle.disabled=true the site lifecycle does not exist any more, and mvn site fails with the same "Unknown lifecycle phase" error as a typo, whose list of available phases ends at deploy instead of site-deploy.

Source: Maven core reference: site lifecycle

Source: Maven core reference: clean lifecycle

Maven 4.0.0-rc-7 keeps the phases and bindings above working but redefines the lifecycle. This page only points at the changes; Maven 4 Lifecycle covers them. All of the following was run on rc-7.

According to the Maven 4 notes, the concurrent builder (-b concurrent) is the way to use the tree for finer-grained parallelism, and the default behaviour stays like Maven 3 for compatibility (not run here).

Source: Maven 4: Lifecycle changes

Source: Maven 4: before- and after-phases, ordering of executions

Source: Maven 4: phase execution scope

The shared lifecycle comparison is in Comparing Ant, Maven and Gradle, and the Java plugin tasks in Gradle Java Projects.