mirror of https://github.com/apache/maven.git
first cut of lifecycle user doc
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@190871 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Brett Leslie Porter
parent
49ea8e4001
commit
8de5475d5a
|
|
@ -0,0 +1,208 @@
|
|||
------
|
||||
Build Lifecycle
|
||||
------
|
||||
Brett Porter
|
||||
------
|
||||
16 June 2005
|
||||
------
|
||||
|
||||
Build Lifecycle
|
||||
|
||||
* Build Lifecycle Basics
|
||||
|
||||
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 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.
|
||||
|
||||
The most common lifecycle phases that would be executed on a project are the following:
|
||||
|
||||
* <<<validate>>> - validate the project is correct and all necessary information is available
|
||||
|
||||
* <<<compile>>> - compile the source code of the project
|
||||
|
||||
* <<<test>>> - test the compiled source code using a suitable unit testing framework. These tests should not
|
||||
require the code be packaged or deployed
|
||||
|
||||
* <<<package>>> - take the compiled code and package it in its distributable format, such as a JAR.
|
||||
|
||||
* <<<integration-test>>> - process and deploy the package if necessary into an environment where integration tests
|
||||
can be run
|
||||
|
||||
* <<<verify>>> - run any checks to verify the package is valid and meets quality criteria
|
||||
|
||||
* <<<install>>> - install the package into the local repository, for use as a dependency in other projects locally
|
||||
|
||||
* <<<deploy>>> - done in an integration or release environment, copies the final package to the remote repository
|
||||
for sharing with other developers and projects.
|
||||
|
||||
Note that for each of these steps, all previous steps are always executed, so you only need to specify the last one
|
||||
you desire on the command line. For example:
|
||||
|
||||
-------
|
||||
m2 install
|
||||
-------
|
||||
|
||||
This command will compile, test, package, verify and install the package into the local repository when run.
|
||||
|
||||
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. For example;
|
||||
|
||||
------
|
||||
m2 clean:clean install
|
||||
------
|
||||
|
||||
This command will traverse into all of the subprojects and run <<<clean:clean>>>, then <<<install>>> (including all of
|
||||
the prior steps).
|
||||
|
||||
* Setting up your Project to Use the Build Lifecycle
|
||||
|
||||
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?
|
||||
|
||||
** Packaging
|
||||
|
||||
The first, and most common way, is to set the <<<packaging>>> for your project. This defaults to <<<jar>>>, so whether
|
||||
you have specifically done it or not, this has already happened. Each packaging contains a list of goals to bind to
|
||||
a particular phase. For example, a JAR will add the following bindings to the lifecycle:
|
||||
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<process-resources>>> | <<<resources:resources>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<compile>>> | <<<compiler:compile>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<process-test-resources>>> | <<<resources:testResources>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<test-compile>>> | <<<compiler:testCompile>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<test>>> | <<<surefire:test>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<package>>> | <<<jar:jar>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<install>>> | <<<install:install>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
| <<<deploy>>> | <<<deploy:deploy>>>
|
||||
*------------------------------+---------------------------------------------------------------------------------------+
|
||||
|
||||
This is an almost standard set of bindings, however, some packages handle them differently. For example, a project
|
||||
that is purely metadata (packaging <<<pom>>>) only binds the <<<install>>> and <<<deploy>>> phases.
|
||||
|
||||
Note that for some packaging tpyes to be available, you may also need to include a particular plugin in your
|
||||
<<<build>>> section, similarly to the next section. One example of a plugin that requires this is the Plexus plugin,
|
||||
which provides a <<<plexus-application>>> and <<<plexus-service>>> packaging.
|
||||
|
||||
** Plugins
|
||||
|
||||
The second way to add goals to phases is to configure plugins in your project. As you will see in the later sections,
|
||||
plugins contain information that says where to bind particular goals 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.
|
||||
|
||||
For example, the Modello plugin always binds <<<modello:java>>> to the <<<generate-sources>>> phase. 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 <<<plugins>>> section of <<<build>>>:
|
||||
|
||||
----
|
||||
...
|
||||
<plugin>
|
||||
<groupId>org.codehaus.modello</groupId>
|
||||
<artifactId>modello-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<configuration>
|
||||
<model>maven.mdo</model>
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
</configuration>
|
||||
<goals>
|
||||
<goal>modello:java</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
...
|
||||
----
|
||||
|
||||
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 <<<modello:java>>>, it only makes sense in the <<<generate-sources>>> 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 <<<touch:timestamp>>> that echos the current time to file, and you want it to
|
||||
run in the <<<process-test-resources>>> phase to indicate when the tests were started. This would be configured like
|
||||
so:
|
||||
|
||||
----
|
||||
...
|
||||
<plugin>
|
||||
<groupId>com.mycompany.example</groupId>
|
||||
<artifactId>touch-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>process-test-resources</phase>
|
||||
<configuration>
|
||||
<file>${project.output.directory}/timestamp.txt</file>
|
||||
</configuration>
|
||||
<goals>
|
||||
<goal>touch:timestamp</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
...
|
||||
----
|
||||
|
||||
TODO
|
||||
|
||||
* Build Lifecycle Phase Reference
|
||||
|
||||
The following phases are all the ones available as of the Maven 2.0 alpha-3 release. They are executed in the order
|
||||
given, up to the point of the one specified.
|
||||
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<validate>>> | validate the project is correct and all necessary information is available.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<generate-sources>>> | generate any source code for inclusion in compilation.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<process-sources>>> | process the source code, for example to filter any values.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<generate-resources>>> | generate resources for inclusion in the package.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<process-resources>>> | copy and process the resources into the destination directory, ready for packaging.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<compile>>> | compile the source code of the project.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<process-classes>>> | post-process the generated files from compilation, for example to do bytecode enhancement on Java classes.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<generate-test-sources>>> | generate any test source code for inclusion in compilation.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<process-test-sources>>> | process the test source code, for example to filter any values.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<generate-test-resources>>> | create resources for testing.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<process-test-resources>>> | copy and process the resources into the test destination directory.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<test-compile>>> | compile the test source code into the test destination directory
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<test>>> | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<package>>> | take the compiled code and package it in its distributable format, such as a JAR.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<integration-test>>> | process and deploy the package if necessary into an environment where integration tests can be run.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<verify>>> | run any checks to verify the package is valid and meets quality criteria.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<install>>> | install the package into the local repository, for use as a dependency in other projects locally.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
| <<<deploy>>> | done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
|
||||
*-------------------------------+--------------------------------------------------------------------------------------+
|
||||
|
||||
* How the Build Lifecycle Affects Plugin Developers
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
Loading…
Reference in New Issue