Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

Introduction to the Build Lifecycle

<h1>Table Of Contents</h1>

<ul>
	<li>Build Lifecycle Basics</li>
</ul>

<ul>
	<li>Setting up your Project to Use the Build Lifecycle
	<ul>
		<li>Packaging</li>
		<li>Plugins</li>
	</ul>
	</li>
</ul>

<ul>
	<li>Build Lifecycle Phase Reference</li>
</ul>

<ul>
	<li>How the Build Lifecycle Affects Plugin Developers
	<ul>
		<li>Binding a Mojo to a Phase</li>
		<li>Specifying a New Packaging</li>
		<li>Creating a Custom Artifact Handler</li>
		<li>Forking a Parallel Lifecycle</li>
	</ul>
	</li>
</ul>

<ul>
	<li>Lifecycle Reference</li>
</ul>

<h1>Build Lifecycle Basics</h1>

Maven 2.0 is based around the central concept of a build lifecycle. What this means is that the process for building 
and distributing a particular artifact (project) is clearly defined.

For the person building a project, this means that it is only necessary to learn a small set of commands to build any 
Maven project, and the POM will ensure they get the results they desired.

There are three built-in Build Lifecycles: default, clean, and site. The default lifecycle handles your project 
deployment, the clean lifecycle handles project cleaning, while the site lifecycle handles the creation of your 
project's site documentation.

<h2>A Build Lifecycle is Made Up of Phases</h2>

Each of these build lifecycles are defined by a different list of build phases, wherein a build phase represents a 
stage in the lifecycle.

For example, the default lifecycle has the following build phases (for a complete list of the build phases, refer 
to the Lifecycle Reference):
<ul>
	<li><code>validate</code> - validate the project is correct and all necessary information is available</li>
</ul>

<ul>
	<li><code>compile</code> - compile the source code of the project</li>
</ul>

<ul>
	<li><code>test</code> - test the compiled source code using a suitable unit testing framework. These tests should not 
require the code be packaged or deployed</li>
</ul>

<ul>
	<li><code>package</code> - take the compiled code and package it in its distributable format, such as a JAR.</li>
</ul>

<ul>
	<li><code>integration-test</code> - process and deploy the package if necessary into an environment where integration tests 
can be run</li>
</ul>

<ul>
	<li><code>verify</code> - run any checks to verify the package is valid and meets quality criteria</li>
</ul>

<ul>
	<li><code>install</code> - install the package into the local repository, for use as a dependency in other projects locally</li>
</ul>

<ul>
	<li><code>deploy</code> - done in an integration or release environment, copies the final package to the remote repository 
for sharing with other developers and projects.</li>
</ul>

These build phases (plus the other build phases not shown here) and executed sequentially to complete the default 
lifecycle. Given the build phases above, this means that when the default lifecycle is used, Maven will first validate 
the project, then will try to compile the sources, run those against the tests, packages the binaries (i.e jar), run 
integration tests against that package, verifies the packaging, install the verifed package to the local repository, 
then depoy the installed package in a specified environment.

To do all those, you only need to call the last build phase to be executed, in this case, deploy. 
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
mvn deploy</td></tr></table>

That is because if you call a build phase, it will execute not only that build phase, but also every build phase 
prior to the called build phase. Thus, doing 
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
mvn integration-test</td></tr></table>

Will do every build phase before it (validate, compile, package), before executing integration-test.

There are more commands that are part of the lifecycle, which will be discussed in the following sections.

It should also be noted that the same command can be used in a multi-module scenario (i.e. a project with one or more 
subprojects). For example; 
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
mvn clean install</td></tr></table>

This command will traverse into all of the subprojects and run <code>clean</code>, then <code>install</code> (including all of 
the prior steps).

<h2>A Build Phase is Made Up of Goals</h2>

However, even though a build phase is responsible for a specific step in the build lifecycle, the manner in which it 
carries out those responsibilities may vary. And this is done by declaring the goals bound to those build phases.

A goal represents a specific task (finer than a build phase) which contributes to the building and managing of a 
project. It may bound itself to zero or more build phases. And a goal not bound to any build phase executes outside of 
the build lifecycle. The order of execution depends on the order in which the goal(s) and the build phase(s) are 
invoked. For exmaple, the in command below. The <code>clean</code> and <code>package</code> arguments are build phases. While the 
<code>dependency:copy-dependencies</code> is a goal. 
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
mvn clean dependency:copy-dependencies package</td></tr></table>

If this were to be executed, the <code>clean</code> phase will first be executed (meaning it will run all preceeding phases, 
plus the <code>clean</code> phase itself), and then the <code>dependency:copy-dependencies</code> goal, before finally executing the 
<code>package</code> phase (and all its preceeding build phases).

Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.

Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it, 
that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals 
(_Note: as of maven-2.0.5, multiple goals bound to a phase are executed in the same order as they are declared in the 
POM_).

<h1>Setting up your Project to Use the Build Lifecycle</h1>

The build lifecycle is simple enough to use, but when you are constructing a Maven build for a project, how do you go 
about assigning tasks to each of those build phases?

<h2>Packaging</h2>

The first, and most common way, is to set the <code>packaging</code> for your project. Some of the valid <code>packaging</code> 
values are <code>jar</code>, <code>war</code>, <code>ear</code>, and <code>pom</code>. If no packaging value have been specified, it will default 
to <code>jar</code>.

Each packaging contains a list of goals to bind to a particular phase. For example, a JAR will bind the following build 
phases to the default lifecycle.
<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>process-resources</code> </td>
<td class="confluenceTd"> <code>resources:resources</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>compile</code> </td>
<td class="confluenceTd"> <code>compiler:compile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-test-resources</code> </td>
<td class="confluenceTd"> <code>resources:testResources</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test-compile</code> </td>
<td class="confluenceTd"> <code>compiler:testCompile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test</code> </td>
<td class="confluenceTd"> <code>surefire:test</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> <code>jar:jar</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> <code>install:install</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> <code>deploy:deploy</code> </td>
</tr>
</tbody></table>

This is an almost standard set of bindings; however, some packages handle them differently. For example, a project 
that is purely metadata (packaging value is <code>pom</code>) only binds the <code>install</code> and <code>deploy</code> phases (for a 
complete list of build-phase-to-goal binding of some of the {{packaging}}s, refer to the 
Lifecycle Reference).

Note that for some packaging types to be available, you may also need to include a particular plugin in your 
<code>build</code> section of your POM (as described in the next section). One example of a plugin that requires this is the 
Plexus plugin, which provides a <code>plexus-application</code> and <code>plexus-service</code> packaging.

<h2>Plugins</h2>

The second way to add goals to phases is to configure plugins in your project. Plugins are artifacts that provides 
goals to Maven. Furthermore, a plugin may have one or more goals wherein each goal represents a capability of that 
plugin. For example, the <code>maven-compiler-plugin</code> has two goals: <code>compile</code> and <code>testCompile</code>. The former 
compiles the source code of your main code, while the latter compiles the source code of your test codes.

As you will see in the later sections, plugins contain information that indicate which lifecycle phase to bind each 
goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want 
run as part of your build.

The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. 
If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed 
first, followed by those configured in the POM. Note that you can use the <code>executions</code> element to gain more 
control over the order of particular goals.

For example, the Modello plugin always binds <code>modello:java</code> to the <code>generate-sources</code> phase (Note: the 
<code>modello:java</code> goal generates java source codes). So to use the Modello plugin and have it generate sources from 
a model and incorporate that into the build, you would add the following to your POM in the <code>plugins</code> section of 
<code>build</code>:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="title=pom.xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6dGl0bGU9cG9tLnhtbH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
...
 &lt;plugin>
 &lt;groupId>org.codehaus.modello&lt;/groupId>
 &lt;artifactId>modello-maven-plugin&lt;/artifactId>
 &lt;executions>
 &lt;execution>
 &lt;configuration>
 &lt;model>maven.mdo&lt;/model>
 &lt;modelVersion>4.0.0&lt;/modelVersion>
 &lt;/configuration>
 &lt;goals>
 &lt;goal>java&lt;/goal>
 &lt;/goals>
 &lt;/execution>
 &lt;/executions>
 &lt;/plugin>
...
</pre></td></tr></table>

You might be wondering why that executions element is there. That is so that you can run the same goal multiple times 
with different configuration if needed. Separate executions can also be given an ID so that during inheritence or the 
application of profiles you can control whether goal configuration is merged or turned into an additional execution.

When multiple executions are given that match a particular phase, they are executed in the order specified in the POM, 
with inherited executions running first.

Now, in the case of <code>modello:java</code>, it only makes sense in the <code>generate-sources</code> phase. But some goals can be 
used in more than one phase, and there may not be a sensible default. For those, you can specify the phase yourself. 
For example, let's say you have a goal <code>display:time</code> that echos the current time to the commandline, and you want 
it to run in the <code>process-test-resources</code> phase to indicate when the tests were started. This would be configured 
like so:
<table class="wysiwyg-macro" data-macro-name="code" data-macro-parameters="title=pom.xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6dGl0bGU9cG9tLnhtbH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
...
 &lt;plugin>
 &lt;groupId>com.mycompany.example&lt;/groupId>
 &lt;artifactId>maven-touch-plugin&lt;/artifactId>
 &lt;executions>
 &lt;execution>
 &lt;phase>process-test-resources&lt;/phase>
 &lt;goals>
 &lt;goal>timestamp&lt;/goal>
 &lt;/goals>
 &lt;/execution>
 &lt;/executions>
 &lt;/plugin>
...
</pre></td></tr></table>

<h1>Lifecycle Reference</h1>

The following lists all build phases of the default, clean and site lifecycle, which are executed in the order given 
up to the point of the one specified.

<h2>Clean Lifecycle</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>pre-clean</code> </td>
<td class="confluenceTd"> executes processes needed prior to the actual project cleaning </td>
</tr>
<tr>
<td class="confluenceTd"> <code>clean</code> </td>
<td class="confluenceTd"> remove all files generated by the previous build </td>
</tr>
<tr>
<td class="confluenceTd"> <code>post-clean</code> </td>
<td class="confluenceTd"> executes processes needed to finalize the project cleaning </td>
</tr>
</tbody></table>

<h2>Default &quot;build&quot; Lifecycle</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>validate</code> </td>
<td class="confluenceTd"> validate the project is correct and all necessary information is available. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>initialize</code> </td>
<td class="confluenceTd"> initializes the build process </td>
</tr>
<tr>
<td class="confluenceTd"> <code>generate-sources</code> </td>
<td class="confluenceTd"> generate any source code for inclusion in compilation. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-sources</code> </td>
<td class="confluenceTd"> process the source code, for example to filter any values. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>generate-resources</code> </td>
<td class="confluenceTd"> generate resources for inclusion in the package. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-resources</code> </td>
<td class="confluenceTd"> copy and process the resources into the destination directory, ready for packaging. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>compile</code> </td>
<td class="confluenceTd"> compile the source code of the project. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-classes</code> </td>
<td class="confluenceTd"> post-process the generated files from compilation, for example to do bytecode enhancement on Java classes. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>generate-test-sources</code> </td>
<td class="confluenceTd"> generate any test source code for inclusion in compilation. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-test-sources</code> </td>
<td class="confluenceTd"> process the test source code, for example to filter any values. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>generate-test-resources</code> </td>
<td class="confluenceTd"> create resources for testing. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-test-resources</code> </td>
<td class="confluenceTd"> copy and process the resources into the test destination directory. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test-compile</code> </td>
<td class="confluenceTd"> compile the test source code into the test destination directory </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test</code> </td>
<td class="confluenceTd"> run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> take the compiled code and package it in its distributable format, such as a JAR. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>pre-integration-test</code> </td>
<td class="confluenceTd"> perform actions required before integration tests are executed. This may involve things such as setting up the required environment. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>integration-test</code> </td>
<td class="confluenceTd"> process and deploy the package if necessary into an environment where integration tests can be run. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>post-integration-test</code> </td>
<td class="confluenceTd"> perform actions required after integration tests have been executed. This may including cleaning up the environment. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>verify</code> </td>
<td class="confluenceTd"> run any checks to verify the package is valid and meets quality criteria. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> install the package into the local repository, for use as a dependency in other projects locally. </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects. </td>
</tr>
</tbody></table>

<h2>Site Lifecycle</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> pre-site </td>
<td class="confluenceTd"> executes processes needed prior to the actual project site generation </td>
</tr>
<tr>
<td class="confluenceTd"> site </td>
<td class="confluenceTd"> generates the project's site documentation </td>
</tr>
<tr>
<td class="confluenceTd"> post-site </td>
<td class="confluenceTd"> executes processes needed to finalize the site generation, and to prepare for site deployment </td>
</tr>
<tr>
<td class="confluenceTd"> site-deploy </td>
<td class="confluenceTd"> deploys the generated site documentation to the specified web server </td>
</tr>
</tbody></table>

Furthermore, some phases have goals binded to it by default. And for the default lifecycle, the bindings depends on 
the <code>packaging</code> value. Here are some of the build-phase-to-goal bindings.

<h1>Lifecycle Default Bindings Reference</h1>

<h2>Clean Lifecycle Bindings</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>clean</code> </td>
<td class="confluenceTd"> <code>clean:clean</code> </td>
</tr>
</tbody></table>

<h2>Default Lifecycle Bindings - EJB / EJB3 / JAR / PAR / RAR / WAR Packaging</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>process-resources</code> </td>
<td class="confluenceTd"> <code>resources:resources</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>compile</code> </td>
<td class="confluenceTd"> <code>compiler:compile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-test-resources</code> </td>
<td class="confluenceTd"> <code>resources:testResource</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test-compile</code> </td>
<td class="confluenceTd"> <code>compiler:testCompile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test</code> </td>
<td class="confluenceTd"> <code>surefire:test</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> <code>ejb:ejb</code> or <code>ejb3:ejb3</code> or <code>jar:jar</code> or <code>par:par</code> or <code>rar:rar</code> or <code>war:war</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> <code>install:install</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> <code>deploy:deploy</code> </td>
</tr>
</tbody></table>

<h2>Default Lifecycle Bindings - EAR Packaging</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>generate-resources</code> </td>
<td class="confluenceTd"> <code>ear:generateApplicationXml</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-resources</code> </td>
<td class="confluenceTd"> <code>resources:resources</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> <code>ear:ear</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> <code>install:install</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> <code>deploy:deploy</code> </td>
</tr>
</tbody></table>

<h2>Default Lifecycle Bindings - maven-plugin Packaging</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>generate-resources</code> </td>
<td class="confluenceTd"> <code>plugin:descriptor</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-resources</code> </td>
<td class="confluenceTd"> <code>resources:resources</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>compile</code> </td>
<td class="confluenceTd"> <code>compiler:compile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>process-test-resources</code> </td>
<td class="confluenceTd"> <code>resources:testResource</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test-compile</code> </td>
<td class="confluenceTd"> <code>compiler:testCompile</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>test</code> </td>
<td class="confluenceTd"> <code>surefire:test</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> <code>jar:jar</code> and <code>plugin:addPluginArtifactMetadata</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> <code>install:install</code> and <code>plugin:updateRegistry</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> <code>deploy:deploy</code> </td>
</tr>
</tbody></table>

<h2>Default Lifecycle Bindings - POM Packaging</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>package</code> </td>
<td class="confluenceTd"> <code>site:attach-descriptor</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>install</code> </td>
<td class="confluenceTd"> <code>install:install</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>deploy</code> </td>
<td class="confluenceTd"> <code>deploy:deploy</code> </td>
</tr>
</tbody></table>

<h2>Site Lifecycle Bindings</h2>

<table class="confluenceTable"><tbody>
<tr>
<td class="confluenceTd"> <code>site</code> </td>
<td class="confluenceTd"> <code>site:site</code> </td>
</tr>
<tr>
<td class="confluenceTd"> <code>site-deploy</code> </td>
<td class="confluenceTd"> <code>site:deploy</code> </td>
</tr>
</tbody></table>