Modified: websites/staging/maven/trunk/content/pom.html
==============================================================================
--- websites/staging/maven/trunk/content/pom.html (original)
+++ websites/staging/maven/trunk/content/pom.html Thu Oct 23 23:00:20 2014
@@ -12,7 +12,9 @@
@import url("./css/site.css");
</style>
<link rel="stylesheet" href="./css/print.css" type="text/css"
media="print" />
- <meta name="Date-Revision-yyyymmdd" content="20141023" />
+ <meta name="author" content="Eric Redmond" />
+ <meta name="Date-Creation-yyyymmdd" content="20080102" />
+ <meta name="Date-Revision-yyyymmdd" content="20141023" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<script src="http://www.google-analytics.com/urchin.js";
type="text/javascript"></script>
@@ -258,168 +260,78 @@
<div id="contentBox">
<div class="section">
<h2><a name="POM_Reference"></a>POM Reference</h2>
-
<ol style="list-style-type: decimal">
-
-<li>
-<p><a href="#Introduction">Introduction</a></p>
-
+<li><a href="#Introduction">Introduction</a>
<ol style="list-style-type: decimal">
-
<li><a href="#What_is_the_POM">What is the POM?</a></li>
-
-<li><a href="#Quick_Overview">Quick Overview</a></li>
- </ol></li>
-
-<li>
-<p><a href="#The_Basics">The Basics</a></p>
-
+<li><a href="#Quick_Overview">Quick Overview</a></li></ol></li>
+<li><a href="#The_Basics">The Basics</a>
<ol style="list-style-type: decimal">
-
<li><a href="#Maven_Coordinates">Maven Coordinates</a></li>
-
<li><a href="#POM_Relationships">POM Relationships</a>
-
<ol style="list-style-type: decimal">
-
<li><a href="#Dependencies">Dependencies</a>
-
<ol style="list-style-type: decimal">
-
-<li><a href="#Exclusions">Exclusions</a></li>
- </ol></li>
- </ol></li>
- </ol>
-
-<div class="source">
-<div class="source">
-<pre>2. [Inheritance](#Inheritance)
- 1. [The Super POM](#The_Super_POM)
- 2. [Dependency Management](#Dependency_Management)
-
-3. [Aggregation (or Multi-Module)](#Aggregation)
- 1. [Inheritance v. Aggregation](#Inheritance_v)
-</pre></div></div>
-
+<li><a href="#Exclusions">Exclusions</a></li></ol></li>
+<li><a href="#Inheritance">Inheritance</a>
+<ol style="list-style-type: decimal">
+<li><a href="#The_Super_POM">The Super POM</a></li>
+<li><a href="#Dependency_Management">Dependency Management</a></li></ol></li>
+<li><a href="#Aggregation">Aggregation (or Multi-Module)</a>
<ol style="list-style-type: decimal">
-
-<li><a href="#Properties">Properties</a></li>
- </ol></li>
-
-<li>
-<p><a href="#Build_Settings">Build Settings</a></p>
-
+<li><a href="#Inheritance_v">Inheritance v.
Aggregation</a></li></ol></li></ol></li>
+<li><a href="#Properties">Properties</a></li></ol></li>
+<li><a href="#Build_Settings">Build Settings</a>
<ol style="list-style-type: decimal">
-
<li><a href="#Build">Build</a>
-
<ol style="list-style-type: decimal">
-
<li><a href="#BaseBuild_Element">The BaseBuild Element Set</a>
-
<ol style="list-style-type: decimal">
-
<li><a href="#Resources">Resources</a></li>
-
<li><a href="#Plugins">Plugins</a></li>
-
-<li><a href="#Plugin_Management">Plugin Management</a></li>
- </ol></li>
- </ol></li>
- </ol>
-
-<div class="source">
-<div class="source">
-<pre>2. [The Build Element Set](#Build_Element)
- 1. [Directories](#Directories)
- 2. [Extensions](#Extensions)
-</pre></div></div>
-
+<li><a href="#Plugin_Management">Plugin Management</a></li></ol></li>
+<li><a href="#Build_Element">The Build Element Set</a>
<ol style="list-style-type: decimal">
-
+<li><a href="#Directories">Directories</a></li>
+<li><a href="#Extensions">Extensions</a></li></ol></li></ol></li>
<li><a href="#Reporting">Reporting</a>
-
<ol style="list-style-type: decimal">
-
-<li><a href="#Report_Sets">Report Sets</a></li>
- </ol></li>
- </ol></li>
-
-<li>
-<p><a href="#More_Project_Information">More Project Information</a></p>
-
+<li><a href="#Report_Sets">Report Sets</a></li></ol></li></ol></li>
+<li><a href="#More_Project_Information">More Project Information</a>
<ol style="list-style-type: decimal">
-
<li><a href="#Licenses">Licenses</a></li>
-
<li><a href="#Organization">Organization</a></li>
-
<li><a href="#Developers">Developers</a></li>
-
-<li><a href="#Contributors">Contributors</a></li>
- </ol></li>
-
-<li>
-<p><a href="#Environment_Settings">Environment Settings</a></p>
-
+<li><a href="#Contributors">Contributors</a></li></ol></li>
+<li><a href="#Environment_Settings">Environment Settings</a>
<ol style="list-style-type: decimal">
-
<li><a href="#Issue_Management">Issue Management</a></li>
-
<li><a href="#Continuous_Integration_Management">Continuous Integration
Management</a></li>
-
<li><a href="#Mailing_Lists">Mailing Lists</a></li>
-
<li><a href="#SCM">SCM</a></li>
-
<li><a href="#Prerequisites">Prerequisites</a></li>
-
<li><a href="#Repositories">Repositories</a></li>
-
<li><a href="#Plugin_Repositories">Plugin Repositories</a></li>
-
<li><a href="#Distribution_Management">Distribution Management</a>
-
<ol style="list-style-type: decimal">
-
<li><a href="#Repository">Repository</a></li>
-
<li><a href="#Site_Distribution">Site Distribution</a></li>
-
-<li><a href="#Relocation">Relocation</a></li>
- </ol></li>
- </ol>
-
-<ol style="list-style-type: decimal">
-
+<li><a href="#Relocation">Relocation</a></li></ol></li>
<li><a href="#Profiles">Profiles</a>
-
<ol style="list-style-type: decimal">
-
<li><a href="#Activation">Activation</a></li>
-
-<li><a href="#The_BaseBuild_Element_Set">The BaseBuild Element Set
<i>(revisited)</i></a></li>
- </ol></li>
- </ol></li>
-
-<li>
-<p><a href="#Final">Final</a></p></li>
-</ol></div>
+<li><a href="#The_BaseBuild_Element_Set">The BaseBuild Element Set
<i>(revisited)</i></a></li></ol></li></ol></li>
+<li><a href="#Final">Final</a></li></ol></div>
<div class="section">
-<h2><a name="Introduction"></a>Introduction</h2>
-
+<h2><a name="Introduction">Introduction</a></h2>
<ul>
-
-<li><a class="externalLink"
href="http://maven.apache.org/xsd/maven-4.0.0.xsd";>The POM 4.0.0 XSD</a> and <a
class="externalLink"
href="http://maven.apache.org/ref/current/maven-model/maven.html";>descriptor
reference documentation</a></li>
-</ul>
+<li><a class="externalLink"
href="http://maven.apache.org/xsd/maven-4.0.0.xsd";>The POM 4.0.0 XSD</a> and <a
class="externalLink"
href="http://maven.apache.org/ref/current/maven-model/maven.html";>descriptor
reference documentation</a></li></ul>
<div class="section">
-<h3><a name="What_is_the_POM"></a>What is the POM?</h3>
-<p>POM stands for “Project Object Model”. It is an XML
representation of a Maven project held in a file named <tt>pom.xml</tt>. When
in the presence of Maven folks, speaking of a project is speaking in the
philosophical sense, beyond a mere collection of files containing code. A
project contains configuration files, as well as the developers involved and
the roles they play, the defect tracking system, the organization and licenses,
the URL of where the project lives, the project’s dependencies, and all
of the other little pieces that come into play to give code life. It is a
one-stop-shop for all things concerning the project. In fact, in the Maven
world, a project need not contain any code at all, merely a
<tt>pom.xml</tt>.</p></div>
+<h3><a name="What_is_the_POM">What is the POM?</a></h3>
+<p>POM stands for "Project Object Model". It is an XML
representation of a Maven project held in a file named <tt>pom.xml</tt>. When
in the presence of Maven folks, speaking of a project is speaking in the
philosophical sense, beyond a mere collection of files containing code. A
project contains configuration files, as well as the developers involved and
the roles they play, the defect tracking system, the organization and licenses,
the URL of where the project lives, the project's dependencies, and all of the
other little pieces that come into play to give code life. It is a
one-stop-shop for all things concerning the project. In fact, in the Maven
world, a project need not contain any code at all, merely a
<tt>pom.xml</tt>.</p></div>
<div class="section">
-<h3><a name="Quick_Overview"></a>Quick Overview</h3>
-<p>This is a listing of the elements directly under the POM’s project
element. Notice that <tt>modelVersion</tt> contains 4.0.0. That is currently
the only supported POM version for both Maven 2 & 3, and is always
required.</p>
-
-<div class="source">
+<h3><a name="Quick_Overview">Quick Overview</a></h3>
+<p>This is a listing of the elements directly under the POM's project element.
Notice that <tt>modelVersion</tt> contains 4.0.0. That is currently the only
supported POM version for both Maven 2 & 3, and is always required.</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -462,13 +374,10 @@
<pluginRepositories>...</pluginRepositories>
<distributionManagement>...</distributionManagement>
<profiles>...</profiles>
-</project>
-</pre></div></div></div></div>
+</project></pre></div></div></div>
<div class="section">
-<h2><a name="The_Basics"></a>The Basics</h2>
-<p>The POM contains all necessary information about a project, as well as
configurations of plugins to be used during the build process. It is,
effectively, the declarative manifestation of the “who”,
“what”, and “where”, while the build lifecycle is
the “when” and “how”. That is not to say that the
POM cannot affect the flow of the lifecycle - it can. For example, by
configuring the <tt>maven-antrun-plugin</tt>, one can effectively embed ant
tasks inside of the POM. It is ultimately a declaration, however. Where as a
<tt>build.xml</tt> tells ant precisely what to do when it is run (procedural),
a POM states its configuration (declarative). If some external force causes the
lifecycle to skip the ant plugin execution, it will not stop the plugins that
are executed from doing their magic. This is unlike a <tt>build.xml</tt> file,
where tasks are almost always dependant on the lines executed before it.</p>
-
-<div class="source">
+<h2><a name="The_Basics">The Basics</a></h2>
+<p>The POM contains all necessary information about a project, as well as
configurations of plugins to be used during the build process. It is,
effectively, the declarative manifestation of the "who",
"what", and "where", while the build lifecycle is the
"when" and "how". That is not to say that the POM cannot
affect the flow of the lifecycle - it can. For example, by configuring the
<tt>maven-antrun-plugin</tt>, one can effectively embed ant tasks inside of the
POM. It is ultimately a declaration, however. Where as a <tt>build.xml</tt>
tells ant precisely what to do when it is run (procedural), a POM states its
configuration (declarative). If some external force causes the lifecycle to
skip the ant plugin execution, it will not stop the plugins that are executed
from doing their magic. This is unlike a <tt>build.xml</tt> file, where tasks
are almost always dependant on the lines executed before it.</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -479,26 +388,16 @@
<groupId>org.codehaus.mojo</groupId>
<artifactId>my-project</artifactId>
<version>1.0</version>
-</project>
-</pre></div></div>
+</project></pre></div>
<div class="section">
-<h3><a name="Maven_Coordinates"></a>Maven Coordinates</h3>
+<h3><a name="Maven_Coordinates">Maven Coordinates</a></h3>
<p>The POM defined above is the minimum that both Maven 2 & 3 will allow.
<tt>groupId:artifactId:version</tt> are all required fields (although, groupId
and version need not be explicitly defined if they are inherited from a parent
- more on inheritance later). The three fields act much like an address and
timestamp in one. This marks a specific place in a repository, acting like a
coordinate system for Maven projects.</p>
-
<ul>
-
-<li><b>groupId</b>: This is generally unique amongst an organization or a
project. For example, all core Maven artifacts do (well, should) live under the
groupId org.apache.maven. Group ID’s do not necessarily use the dot
notation, for example, the junit project. Note that the dot-notated groupId
does not have to correspond to the package structure that the project contains.
It is, however, a good practice to follow. When stored within a repository, the
group acts much like the Java packaging structure does in an operating system.
The dots are replaced by OS specific directory separators (such as
‘/’ in Unix) which becomes a relative directory structure from
the base repository. In the example given, the <tt>org.codehaus.mojo</tt> group
lives within the directory <tt>$M2_REPO/org/codehaus/mojo</tt>.</li>
-
-<li><b>artifactId</b>: The artifactId is generally the name that the project
is known by. Although the groupId is important, people within the group will
rarely mention the groupId in discussion (they are often all be the same ID,
such as the <a class="externalLink" href="http://mojo.codehaus.org/";>Codehaus
Mojo</a> project groupId: <tt>org.codehaus.mojo</tt>). It, along with the
groupId, create a key that separates this project from every other project in
the world (at least, it should :) ). Along with the groupId, the artifactId
fully defines the artifact’s living quarters within the repository. In
the case of the above project, <tt>my-project</tt> lives in
<tt>$M2_REPO/org/codehaus/mojo/my-project</tt>.</li>
-
-<li>
-<p><b>version</b>: This is the last piece of the naming puzzle.
<tt>groupId:artifactId</tt> denote a single project but they cannot delineate
which incarnation of that project we are talking about. Do we want the
<tt>junit:junit</tt> of today (version 4), or of four years ago (version 2)? In
short: code changes, those changes should be versioned, and this element keeps
those versions in line. It is also used within an artifact’s repository
to separate versions from each other. <tt>my-project</tt> version 1.0 files
live in the directory structure
<tt>$M2_REPO/org/codehaus/mojo/my-project/1.0</tt>.</p>
+<li><b>groupId</b>: This is generally unique amongst an organization or a
project. For example, all core Maven artifacts do (well, should) live under the
groupId org.apache.maven. Group ID's do not necessarily use the dot notation,
for example, the junit project. Note that the dot-notated groupId does not have
to correspond to the package structure that the project contains. It is,
however, a good practice to follow. When stored within a repository, the group
acts much like the Java packaging structure does in an operating system. The
dots are replaced by OS specific directory separators (such as '/' in Unix)
which becomes a relative directory structure from the base repository. In the
example given, the <tt>org.codehaus.mojo</tt> group lives within the directory
<tt>$M2_REPO/org/codehaus/mojo</tt>.</li>
+<li><b>artifactId</b>: The artifactId is generally the name that the project
is known by. Although the groupId is important, people within the group will
rarely mention the groupId in discussion (they are often all be the same ID,
such as the <a class="externalLink" href="http://mojo.codehaus.org/";>Codehaus
Mojo</a> project groupId: <tt>org.codehaus.mojo</tt>). It, along with the
groupId, create a key that separates this project from every other project in
the world (at least, it should :) ). Along with the groupId, the artifactId
fully defines the artifact's living quarters within the repository. In the case
of the above project, <tt>my-project</tt> lives in
<tt>$M2_REPO/org/codehaus/mojo/my-project</tt>.</li>
+<li><b>version</b>: This is the last piece of the naming puzzle.
<tt>groupId:artifactId</tt> denote a single project but they cannot delineate
which incarnation of that project we are talking about. Do we want the
<tt>junit:junit</tt> of today (version 4), or of four years ago (version 2)? In
short: code changes, those changes should be versioned, and this element keeps
those versions in line. It is also used within an artifact's repository to
separate versions from each other. <tt>my-project</tt> version 1.0 files live
in the directory structure <tt>$M2_REPO/org/codehaus/mojo/my-project/1.0</tt>.
<p>The three elements given above point to a specific version of a project
letting Maven knows <i>who</i> we are dealing with, and <i>when</i> in its
software lifecycle we want them.</p></li>
-
-<li>
-<p><b>packaging</b>: Now that we have our address structure of
<tt>groupId:artifactId:version</tt>, there is one more standard label to give
us a really complete address. That is the project’s artifact type. In
our case, the example POM for <tt>org.codehaus.mojo:my-project:1.0</tt> defined
above will be packaged as a <tt>jar</tt>. We could make it into a <tt>war</tt>
by declaring a different packaging:</p>
-
-<div class="source">
+<li><b>packaging</b>: Now that we have our address structure of
<tt>groupId:artifactId:version</tt>, there is one more standard label to give
us a really complete address. That is the project's artifact type. In our case,
the example POM for <tt>org.codehaus.mojo:my-project:1.0</tt> defined above
will be packaged as a <tt>jar</tt>. We could make it into a <tt>war</tt> by
declaring a different packaging:
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -507,22 +406,16 @@
...
<packaging>war</packaging>
...
-</project>
-</pre></div></div>
+</project></pre></div>
<p>When no packaging is declared, Maven assumes the artifact is the default:
<tt>jar</tt>. The valid types are Plexus role-hints (read more on Plexus for a
explanation of roles and role-hints) of the component role
<tt>org.apache.maven.lifecycle.mapping.LifecycleMapping</tt>. The current core
packaging values are: <tt>pom</tt>, <tt>jar</tt>, <tt>maven-plugin</tt>,
<tt>ejb</tt>, <tt>war</tt>, <tt>ear</tt>, <tt>rar</tt>, <tt>par</tt>. These
define the default list of goals which execute to each corresponding build
lifecycle stage for a particular package structure.</p>
<p>You will sometimes see Maven print out a project coordinate as
<tt>groupId:artifactId:packaging:version</tt>.</p></li>
-
-<li>
-<p><b>classifier</b>: You may occasionally find a fifth element on the
coordinate, and that is the <tt>classifier</tt>. We will visit the classifier
later, but for now it suffices to know that those kinds of projects are
displayed as <tt>groupId:artifactId:packaging:classifier:version</tt>.</p></li>
-</ul></div>
+<li><b>classifier</b>: You may occasionally find a fifth element on the
coordinate, and that is the <tt>classifier</tt>. We will visit the classifier
later, but for now it suffices to know that those kinds of projects are
displayed as
<tt>groupId:artifactId:packaging:classifier:version</tt>.</li></ul></div>
<div class="section">
-<h3><a name="POM_Relationships"></a>POM Relationships</h3>
-<p>One powerful aspect of Maven is in its handling of project relationships;
that includes dependencies (and transitive dependencies), inheritance, and
aggregation (multi-module projects). Dependency management has a long tradition
of being a complicated mess for anything but the most trivial of projects.
<i>“Jarmageddon”</i> quickly ensues as the dependency tree
becomes large and complicated. <i>“Jar Hell”</i> follows, where
versions of dependencies on one system are not equivalent to versions as those
developed with, either by the wrong version given, or conflicting versions
between similarly named jars. Maven solves both problems through a common local
repository from which to link projects correctly, versions and all.</p>
+<h3><a name="POM_Relationships">POM Relationships</a></h3>
+<p>One powerful aspect of Maven is in its handling of project relationships;
that includes dependencies (and transitive dependencies), inheritance, and
aggregation (multi-module projects). Dependency management has a long tradition
of being a complicated mess for anything but the most trivial of projects.
<i>"Jarmageddon"</i> quickly ensues as the dependency tree becomes
large and complicated. <i>"Jar Hell"</i> follows, where versions of
dependencies on one system are not equivalent to versions as those developed
with, either by the wrong version given, or conflicting versions between
similarly named jars. Maven solves both problems through a common local
repository from which to link projects correctly, versions and all.</p>
<div class="section">
-<h4><a name="Dependencies"></a>Dependencies</h4>
+<h4><a name="Dependencies">Dependencies</a></h4>
<p>The cornerstone of the POM is its dependency list. Most every project
depends upon others to build and run correctly, and if all Maven does for you
is manage this list for you, you have gained a lot. Maven downloads and links
the dependencies for you on compilation and other goals that require them. As
an added bonus, Maven brings in the dependencies of those dependencies
(transitive dependencies), allowing your list to focus solely on the
dependencies your project requires.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -541,69 +434,33 @@
...
</dependencies>
...
-</project>
-</pre></div></div>
-
+</project></pre></div>
<ul>
-
-<li>
-<p><b>groupId</b>, <b>artifactId</b>, <b>version</b>:\ These elements are
self-explanatory, and you will see them often. This trinity represents the
coordinate of a specific project in time, demarcating it as a dependency of
this project. You may be thinking: “This means that my project can only
depend upon Maven artifacts!” The answer is, “Of course, but
that’s a good thing.” This forces you to depend solely on
dependencies that Maven can manage. There are times, unfortunately, when a
project cannot be downloaded from the central Maven repository. For example, a
project may depend upon a jar that has a closed-source license which prevents
it from being in a central repository. There are three methods for dealing with
this scenario.</p>
-
-<ol style="list-style-type: decimal">
-
-<li>Install the dependency locally using the install plugin. The method is the
simplest recommended method. For example:</li>
- </ol>
-
-<div class="source">
-<div class="source">
-<pre> mvn install:install-file -Dfile=non-maven-proj.jar
-DgroupId=some.group -DartifactId=non-maven-proj -Dversion=1 -Dpackaging=jar
-
-Notice that an address is still required, only this time you use
-the command line and the install plugin will create a POM for
-you with the given address.
-</pre></div></div>
-
+<li><b>groupId</b>, <b>artifactId</b>, <b>version</b>:<br />These elements are
self-explanatory, and you will see them often. This trinity represents the
coordinate of a specific project in time, demarcating it as a dependency of
this project. You may be thinking: "This means that my project can only
depend upon Maven artifacts!" The answer is, "Of course, but that's a
good thing." This forces you to depend solely on dependencies that Maven
can manage. There are times, unfortunately, when a project cannot be downloaded
from the central Maven repository. For example, a project may depend upon a jar
that has a closed-source license which prevents it from being in a central
repository. There are three methods for dealing with this scenario.
<ol style="list-style-type: decimal">
-
-<li>Create your own repository and deploy it there. This is a favorite method
for companies with an intranet and need to be able to keep everyone in synch.
There is a Maven goal called <tt>deploy:deploy-file</tt> which is similar to
the <tt>install:install-file</tt> goal (read the plugin’s goal page for
more information).</li>
-
-<li>Set the dependency scope to <tt>system</tt> and define a
<tt>systemPath</tt>. This is not recommended, however, but leads us to
explaining the following elements:</li>
- </ol></li>
-
-<li>
-<p><b>classifier</b>:\ The classifier allows to distinguish artifacts that
were built from the same POM but differ in their content. It is some optional
and arbitrary string that - if present - is appended to the artifact name just
after the version number.</p>
+<li>Install the dependency locally using the install plugin. The method is the
simplest recommended method. For example:
+<div>
+<pre>mvn install:install-file -Dfile=non-maven-proj.jar -DgroupId=some.group
-DartifactId=non-maven-proj -Dversion=1 -Dpackaging=jar</pre></div>
+<p>Notice that an address is still required, only this time you use the
command line and the install plugin will create a POM for you with the given
address.</p></li>
+<li>Create your own repository and deploy it there. This is a favorite method
for companies with an intranet and need to be able to keep everyone in synch.
There is a Maven goal called <tt>deploy:deploy-file</tt> which is similar to
the <tt>install:install-file</tt> goal (read the plugin's goal page for more
information).</li>
+<li>Set the dependency scope to <tt>system</tt> and define a
<tt>systemPath</tt>. This is not recommended, however, but leads us to
explaining the following elements:</li></ol></li>
+<li><b>classifier</b>:<br />The classifier allows to distinguish artifacts
that were built from the same POM but differ in their content. It is some
optional and arbitrary string that - if present - is appended to the artifact
name just after the version number.
<p>As a motivation for this element, consider for example a project that
offers an artifact targeting JRE 1.5 but at the same time also an artifact that
still supports JRE 1.4. The first artifact could be equipped with the
classifier <tt>jdk15</tt> and the second one with <tt>jdk14</tt> such that
clients can choose which one to use.</p>
-<p>Another common use case for classifiers is the need to attach secondary
artifacts to the project’s main artifact. If you browse the Maven
central repository, you will notice that the classifiers <tt>sources</tt> and
<tt>javadoc</tt> are used to deploy the project source code and API docs along
with the packaged class files.</p></li>
-
-<li>
-<p><b>type</b>:\ Corresponds to the dependant artifact’s
<tt>packaging</tt> type. This defaults to <tt>jar</tt>. While it usually
represents the extension on the filename of the dependency, that is not always
the case. A type can be mapped to a different extension and a classifier. The
type often corresponds to the packaging used, though this is also not always
the case. Some examples are <tt>jar</tt>, <tt>ejb-client</tt> and
<tt>test-jar</tt>. New types can be defined by plugins that set
<tt>extensions</tt> to true, so this is not a complete list.</p></li>
-
-<li><b>scope</b>:\ This element refers to the classpath of the task at hand
(compiling and runtime, testing, etc.) as well as how to limit the transitivity
of a dependency. There are five scopes available:
-
+<p>Another common use case for classifiers is the need to attach secondary
artifacts to the project's main artifact. If you browse the Maven central
repository, you will notice that the classifiers <tt>sources</tt> and
<tt>javadoc</tt> are used to deploy the project source code and API docs along
with the packaged class files.</p></li>
+<li><b>type</b>:<br />Corresponds to the dependant artifact's
<tt>packaging</tt> type. This defaults to <tt>jar</tt>. While it usually
represents the extension on the filename of the dependency, that is not always
the case. A type can be mapped to a different extension and a classifier. The
type often corresponds to the packaging used, though this is also not always
the case. Some examples are <tt>jar</tt>, <tt>ejb-client</tt> and
<tt>test-jar</tt>. New types can be defined by plugins that set
<tt>extensions</tt> to true, so this is not a complete list.</li>
+<li><b>scope</b>:<br />This element refers to the classpath of the task at
hand (compiling and runtime, testing, etc.) as well as how to limit the
transitivity of a dependency. There are five scopes available:
<ul>
-
<li><b>compile</b> - this is the default scope, used if none is specified.
Compile dependencies are available in all classpaths. Furthermore, those
dependencies are propagated to dependent projects.</li>
-
<li><b>provided</b> - this is much like compile, but indicates you expect the
JDK or a container to provide it at runtime. It is only available on the
compilation and test classpath, and is not transitive.</li>
-
<li><b>runtime</b> - this scope indicates that the dependency is not required
for compilation, but is for execution. It is in the runtime and test
classpaths, but not the compile classpath.</li>
-
<li><b>test</b> - this scope indicates that the dependency is not required for
normal use of the application, and is only available for the test compilation
and execution phases.</li>
-
-<li><b>system</b> - this scope is similar to <tt>provided</tt> except that you
have to provide the JAR which contains it explicitly. The artifact is always
available and is not looked up in a repository.</li>
- </ul></li>
-
-<li><b>systemPath</b>:\ is used <i>only</i> if the the dependency
<tt>scope</tt> is <tt>system</tt>. Otherwise, the build will fail if this
element is set. The path must be absolute, so it is recommended to use a
property to specify the machine-specific path (more on <tt>properties</tt>
below), such as <tt>${java.home}/lib</tt>. Since it is assumed that system
scope dependencies are installed <i>a priori</i>, Maven will not check the
repositories for the project, but instead checks to ensure that the file
exists. If not, Maven will fail the build and suggest that you download and
install it manually.</li>
-
-<li>
-<p><b>optional</b>:\ Marks optional a dependency when this project itself is a
dependency. Confused? For example, imagine a project <tt>A</tt> that depends
upon project <tt>B</tt> to compile a portion of code that may not be used at
runtime, then we may have no need for project <tt>B</tt> for all project. So if
project <tt>X</tt> adds project <tt>A</tt> as its own dependency, then Maven
will not need to install project <tt>B</tt> at all. Symbolically, if
<tt>=></tt> represents a required dependency, and <tt>--></tt> represents
optional, although <tt>A=>B</tt> may be the case when building A
<tt>X=>A-->B</tt> would be the case when building <tt>X</tt>.</p>
-<p>In the shortest terms, <tt>optional</tt> lets other projects know that,
when you use this project, you do not require this dependency in order to work
correctly.</p></li>
-</ul>
+<li><b>system</b> - this scope is similar to <tt>provided</tt> except that you
have to provide the JAR which contains it explicitly. The artifact is always
available and is not looked up in a repository.</li></ul></li>
+<li><b>systemPath</b>:<br />is used <i>only</i> if the the dependency
<tt>scope</tt> is <tt>system</tt>. Otherwise, the build will fail if this
element is set. The path must be absolute, so it is recommended to use a
property to specify the machine-specific path (more on <tt>properties</tt>
below), such as <tt>${java.home}/lib</tt>. Since it is assumed that system
scope dependencies are installed <i>a priori</i>, Maven will not check the
repositories for the project, but instead checks to ensure that the file
exists. If not, Maven will fail the build and suggest that you download and
install it manually.</li>
+<li><b>optional</b>:<br />Marks optional a dependency when this project itself
is a dependency. Confused? For example, imagine a project <tt>A</tt> that
depends upon project <tt>B</tt> to compile a portion of code that may not be
used at runtime, then we may have no need for project <tt>B</tt> for all
project. So if project <tt>X</tt> adds project <tt>A</tt> as its own
dependency, then Maven will not need to install project <tt>B</tt> at all.
Symbolically, if <tt>=></tt> represents a required dependency, and
<tt>--></tt> represents optional, although <tt>A=>B</tt> may be the case
when building A <tt>X=>A-->B</tt> would be the case when building
<tt>X</tt>.
+<p>In the shortest terms, <tt>optional</tt> lets other projects know that,
when you use this project, you do not require this dependency in order to work
correctly.</p></li></ul>
<div class="section">
-<h5><a name="Exclusions"></a>Exclusions</h5>
-<p>Exclusions explicitly tell Maven that you don’t want to include the
specified project that is a dependency of this dependency (in other words, its
transitive dependency). For example, the <tt>maven-embedder</tt> requires
<tt>maven-core</tt>, and we do not wish to use it or its dependencies, then we
would add it as an <tt>exclusion</tt>.</p>
-
-<div class="source">
+<h5><a name="Exclusions">Exclusions</a></h5>
+<p>Exclusions explicitly tell Maven that you don't want to include the
specified project that is a dependency of this dependency (in other words, its
transitive dependency). For example, the <tt>maven-embedder</tt> requires
<tt>maven-core</tt>, and we do not wish to use it or its dependencies, then we
would add it as an <tt>exclusion</tt>.</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -625,11 +482,8 @@ you with the given address.
...
</dependencies>
...
-</project>
-</pre></div></div>
-<p>It is also sometimes useful to clip a dependency’s transitive
dependencies. A dependency may have incorrectly specified scopes, or
dependencies that conflict with other dependencies in your project. Using
wildcard excludes makes it easy to exclude all a dependency’s transitive
dependencies. In the case below you may be working with the maven-embedder and
you want to manage the dependencies you use yourself, so you clip all the
transitive dependencies:</p>
-
-<div class="source">
+</project></pre></div>
+<p>It is also sometimes useful to clip a dependency's transitive dependencies.
A dependency may have incorrectly specified scopes, or dependencies that
conflict with other dependencies in your project. Using wildcard excludes makes
it easy to exclude all a dependency's transitive dependencies. In the case
below you may be working with the maven-embedder and you want to manage the
dependencies you use yourself, so you clip all the transitive dependencies:</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -651,18 +505,12 @@ you with the given address.
...
</dependencies>
...
-</project>
-</pre></div></div>
-
+</project></pre></div>
<ul>
-
-<li><b>exclusions</b>: Exclusions contain one or more <tt>exclusion</tt>
elements, each containing a <tt>groupId</tt> and <tt>artifactId</tt> denoting a
dependency to exclude. Unlike <tt>optional</tt>, which may or may not be
installed and used, <tt>exclusions</tt> actively remove themselves from the
dependency tree.</li>
-</ul></div></div>
+<li><b>exclusions</b>: Exclusions contain one or more <tt>exclusion</tt>
elements, each containing a <tt>groupId</tt> and <tt>artifactId</tt> denoting a
dependency to exclude. Unlike <tt>optional</tt>, which may or may not be
installed and used, <tt>exclusions</tt> actively remove themselves from the
dependency tree.</li></ul></div></div>
<div class="section">
-<h4><a name="Inheritance"></a>Inheritance</h4>
+<h4><a name="Inheritance">Inheritance</a></h4>
<p>One powerful addition that Maven brings to build management is the concept
of project inheritance. Although in build systems such as Ant, inheritance can
certainly be simulated, Maven has gone the extra step in making project
inheritance explicit to the project object model.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -674,27 +522,15 @@ you with the given address.
<artifactId>my-parent</artifactId>
<version>2.0</version>
<packaging>pom</packaging>
-</project>
-</pre></div></div>
+</project></pre></div>
<p>The <tt>packaging</tt> type required to be <tt>pom</tt> for <i>parent</i>
and <i>aggregation</i> (multi-module) projects. These types define the goals
bound to a set of lifecycle stages. For example, if packaging is <tt>jar</tt>,
then the <tt>package</tt> phase will execute the <tt>jar:jar</tt> goal. If the
packaging is <tt>pom</tt>, the goal executed will be
<tt>site:attach-descriptor</tt>. Now we may add values to the parent POM, which
will be inherited by its children. The elements in the parent POM that are
inherited by its children are:</p>
-
<ul>
-
<li>dependencies</li>
-
<li>developers and contributors</li>
-
<li>plugin lists</li>
-
<li>reports lists</li>
-
<li>plugin executions with matching ids</li>
-
-<li>plugin configuration</li>
-</ul>
-<!-- -->
-
-<div class="source">
+<li>plugin configuration</li></ul>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -710,15 +546,12 @@ you with the given address.
</parent>
<artifactId>my-project</artifactId>
-</project>
-</pre></div></div>
-<p>Notice the <tt>relativePath</tt> element. It is not required, but may be
used as a signifier to Maven to first search the path given for this
project’s parent, before searching the local and then remote
repositories.</p>
-<p>To see inheritance in action, just have a look at the <a
class="externalLink"
href="http://svn.apache.org/viewvc/maven/pom/trunk/asf/pom.xml?view=markup";>ASF</a>
or <a class="externalLink"
href="http://svn.apache.org/viewvc/maven/pom/trunk/maven/pom.xml?view=markup";>Maven</a>
parent POM’s.</p>
+</project></pre></div>
+<p>Notice the <tt>relativePath</tt> element. It is not required, but may be
used as a signifier to Maven to first search the path given for this project's
parent, before searching the local and then remote repositories.</p>
+<p>To see inheritance in action, just have a look at the <a
class="externalLink"
href="http://svn.apache.org/viewvc/maven/pom/trunk/asf/pom.xml?view=markup";>ASF</a>
or <a class="externalLink"
href="http://svn.apache.org/viewvc/maven/pom/trunk/maven/pom.xml?view=markup";>Maven</a>
parent POM's. </p>
<div class="section">
-<h5><a name="The_Super_POM"></a>The Super POM</h5>
+<h5><a name="The_Super_POM">The Super POM</a></h5>
<p>Similar to the inheritance of objects in object oriented programming, POMs
that extend a parent POM inherit certain values from that parent. Moreover,
just as Java objects ultimately inherit from <tt>java.lang.Object</tt>, all
Project Object Models inherit from a base Super POM. The snippet below is the
Super POM for Maven 3.0.4.</p>
-
-<div class="source">
<div class="source">
<pre><project>
<modelVersion>4.0.0</modelVersion>
@@ -847,21 +680,16 @@ you with the given address.
</profiles>
</project>
-</pre></div></div>
+</pre></div>
<p>You can take a look at how the Super POM affects your Project Object Model
by creating a minimal <tt>pom.xml</tt> and executing on the command line:
<tt>mvn help:effective-pom</tt></p></div>
<div class="section">
-<h5><a name="Dependency_Management"></a>Dependency Management</h5>
+<h5><a name="Dependency_Management">Dependency Management</a></h5>
<p>Besides inheriting certain top-level elements, parents have elements to
configure values for child POMs and transitive dependencies. One of those
elements is <tt>dependencyManagement</tt>.</p>
-
<ul>
-
-<li><b>dependencyManagement</b>: is used by POMs to help manage dependency
information across all of its children. If the <tt>my-parent</tt> project uses
<tt>dependencyManagement</tt> to define a dependency on
<tt>junit:junit:4.0</tt>, then POMs inheriting from this one can set their
dependency giving the <tt>groupId</tt>=<tt>junit</tt> and
<tt>artifactId</tt>=<tt>junit</tt> only, then Maven will fill in the
<tt>version</tt> set by the parent. The benefits of this method are obvious.
Dependency details can be set in one central location, which will propagate to
all inheriting POMs. In addition, the version and scope of artifacts which are
incorporated from transitive dependencies may also be controlled by specifying
them in a dependency management section.</li>
-</ul></div></div>
+<li><b>dependencyManagement</b>: is used by POMs to help manage dependency
information across all of its children. If the <tt>my-parent</tt> project uses
<tt>dependencyManagement</tt> to define a dependency on
<tt>junit:junit:4.0</tt>, then POMs inheriting from this one can set their
dependency giving the <tt>groupId</tt>=<tt>junit</tt> and
<tt>artifactId</tt>=<tt>junit</tt> only, then Maven will fill in the
<tt>version</tt> set by the parent. The benefits of this method are obvious.
Dependency details can be set in one central location, which will propagate to
all inheriting POMs. In addition, the version and scope of artifacts which are
incorporated from transitive dependencies may also be controlled by specifying
them in a dependency management section.</li></ul></div></div>
<div class="section">
-<h4><a name="Aggregation_or_Multi-Module"></a>Aggregation (or
Multi-Module)</h4>
+<h4><a name="Aggregation_or_Multi-Module"></a><a
name="Aggregation">Aggregation</a> (or Multi-Module)</h4>
<p>A project with modules is known as a multimodule, or aggregator project.
Modules are projects that this POM lists, and are executed as a group. An
<tt>pom</tt> packaged project may aggregate the build of a set of projects by
listing them as modules, which are relative directories to those projects.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -878,42 +706,30 @@ you with the given address.
<module>my-project</module>
<module>another-project</module>
</modules>
-</project>
-</pre></div></div>
+</project></pre></div>
<p>You do not need to consider the inter-module dependencies yourself when
listing the modules, i.e. the ordering of the modules given by the POM is not
important. Maven will topologically sort the modules such that dependencies are
always build before dependent modules.</p>
-<p>To see aggregation in action, just have a look at the <a
class="externalLink"
href="http://svn.apache.org/viewvc/maven/maven-3/trunk/pom.xml?view=markup";>Maven</a>
or <a class="externalLink"
href="http://svn.apache.org/viewvc/maven/plugins/trunk/pom.xml?view=markup";>Maven
Core Plugins</a> base POM’s.</p>
+<p>To see aggregation in action, just have a look at the <a
class="externalLink"
href="http://svn.apache.org/viewvc/maven/maven-3/trunk/pom.xml?view=markup";>Maven</a>
or <a class="externalLink"
href="http://svn.apache.org/viewvc/maven/plugins/trunk/pom.xml?view=markup";>Maven
Core Plugins</a> base POM's. </p>
<div class="section">
-<h5><a name="A_final_note_on_Inheritance_v._Aggregation"></a>A final note on
Inheritance v. Aggregation</h5>
+<h5><a name="A_final_note_on_Inheritance_v._Aggregation"></a>A final note on
<a name="Inheritance_v">Inheritance v</a>. Aggregation</h5>
<p>Inheritance and aggregation create a nice dynamic to control builds through
a single, high-level POM. You will often see projects that are both parents and
aggregators. For example, the entire maven core runs through a single base POM
<a class="externalLink"
href="http://svn.apache.org/viewvc/maven/maven-3/trunk/pom.xml?view=markup";><tt>org.apache.maven:maven</tt></a>,
so building the Maven project can be executed by a single command: <tt>mvn
compile</tt>. However, although both POM projects, an aggregator project and a
parent project are not one in the same and should not be confused. A POM
project may be inherited from - but does not necessarily have - any modules
that it aggregates. Conversely, a POM project may aggregate projects that do
not inherit from it.</p></div></div></div>
<div class="section">
-<h3><a name="Properties"></a>Properties</h3>
+<h3><a name="Properties">Properties</a></h3>
<p>Properties are the last required piece in understanding POM basics. Maven
properties are value placeholder, like properties in Ant. Their values are
accessible anywhere within a POM by using the notation <tt>${X}</tt>, where
<tt>X</tt> is the property.</p>
<p>They come in five different styles:</p>
-
<ol style="list-style-type: decimal">
-
-<li>
-<p><tt>env.X</tt>: Prefixing a variable with “env.” will return
the shell’s environment variable. For example, <tt>${env.PATH}</tt>
contains the PATH environment variable.</p>
+<li><tt>env.X</tt>: Prefixing a variable with "env." will return the
shell's environment variable. For example, <tt>${env.PATH}</tt> contains the
PATH environment variable.
<p><i>Note:</i> While environment variables themselves are case-insensitive on
Windows, lookup of properties is case-sensitive. In other words, while the
Windows shell returns the same value for <tt>%PATH%</tt> and <tt>%Path%</tt>,
Maven distinguishes between <tt>${env.PATH}</tt> and <tt>${env.Path}</tt>. As
of Maven 2.1.0, <b>the names of environment variables are normalized to all
upper-case</b> for the sake of reliability.</p></li>
-
-<li>
-<p><tt>project.x</tt>: A dot (.) notated path in the POM will contain the
corresponding element’s value. For example:
<tt><project><version>1.0</version></project></tt> is
accessible via <tt>${project.version}</tt>.</p></li>
-
-<li><tt>settings.x</tt>: A dot (.) notated path in the <tt>settings.xml</tt>
will contain the corresponding element’s value. For example:
<tt><settings><offline>false</offline></settings></tt>
is accessible via <tt>${settings.offline}</tt>.</li>
-
+<li><tt>project.x</tt>: A dot (.) notated path in the POM will contain the
corresponding element's value. For example:
<tt><project><version>1.0</version></project></tt> is
accessible via <tt>${project.version}</tt>.</li>
+<li><tt>settings.x</tt>: A dot (.) notated path in the <tt>settings.xml</tt>
will contain the corresponding element's value. For example:
<tt><settings><offline>false</offline></settings></tt>
is accessible via <tt>${settings.offline}</tt>.</li>
<li>Java System Properties: All properties accessible via
<tt>java.lang.System.getProperties()</tt> are available as POM properties, such
as <tt>${java.home}</tt>.</li>
-
-<li><tt>x</tt>: Set within a <tt><properties /></tt> element in the POM.
The value of
<tt><properties><someVar>value</someVar></properies></tt>
may be used as <tt>${someVar}</tt>.</li>
-</ol></div></div>
+<li><tt>x</tt>: Set within a <tt><properties /></tt> element in the POM.
The value of
<tt><properties><someVar>value</someVar></properies></tt>
may be used as <tt>${someVar}</tt>.</li></ol></div></div>
<div class="section">
-<h2><a name="Build_Settings"></a>Build Settings</h2>
-<p>Beyond the basics of the POM given above, there are two more elements that
must be understood before claiming basic competency of the POM. They are the
<tt>build</tt> element, that handles things like declaring your
project’s directory structure and managing plugins; and the
<tt>reporting</tt> element, that largely mirrors the build element for
reporting purposes.</p>
+<h2><a name="Build_Settings">Build Settings</a></h2>
+<p>Beyond the basics of the POM given above, there are two more elements that
must be understood before claiming basic competency of the POM. They are the
<tt>build</tt> element, that handles things like declaring your project's
directory structure and managing plugins; and the <tt>reporting</tt> element,
that largely mirrors the build element for reporting purposes.</p>
<div class="section">
-<h3><a name="Build"></a>Build</h3>
+<h3><a name="Build">Build</a></h3>
<p>According to the POM 4.0.0 XSD, the <tt>build</tt> element is conceptually
divided into two parts: there is a <tt>BaseBuild</tt> type which contains the
set of elements common to both <tt>build</tt> elements (the top-level build
element under <tt>project</tt> and the build element under <tt>profiles</tt>,
covered below); and there is the <tt>Build</tt> type, which contains the
<tt>BaseBuild</tt> set as well as more elements for the top level definition.
Let us begin with an analysis of the common elements between the two.</p>
-<p><i>Note: These different</i> <tt>build</tt> <i>elements may be denoted
“project build” and “profile build”.</i></p>
-
-<div class="source">
+<p><i>Note: These different</i> <tt>build</tt> <i>elements may be denoted
"project build" and "profile build".</i></p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -929,14 +745,11 @@ you with the given address.
<build>...</build>
</profile>
</profiles>
-</project>
-</pre></div></div>
+</project></pre></div>
<div class="section">
-<h4><a name="The_BaseBuild_Element_Set"></a>The BaseBuild Element Set</h4>
+<h4><a name="The_BaseBuild_Element_Set"></a>The <a
name="BaseBuild_Element">BaseBuild Element</a> Set</h4>
<p><tt>BaseBuild</tt> is exactly as it sounds: the base set of elements
between the two <tt>build</tt> elements in the POM.</p>
-
-<div class="source">
-<div class="source">
+<div>
<pre><build>
<defaultGoal>install</defaultGoal>
<directory>${basedir}/target</directory>
@@ -945,27 +758,17 @@ you with the given address.
<filter>filters/filter1.properties</filter>
</filters>
...
-</build>
-</pre></div></div>
-
+</build></pre></div>
<ul>
-
<li><b>defaultGoal</b>: the default goal or phase to execute if none is given.
If a goal is given, it should be defined as it is in the command line (such as
<tt>jar:jar</tt>). The same goes for if a phase is defined (such as
install).</li>
-
-<li><b>directory</b>: This is the directory where the build will dump its
files or, in Maven parlance, the build’s target. It aptly defaults to
<tt>${basedir}/target</tt>.</li>
-
-<li><b>finalName</b>: This is the name of the bundled project when it is
finally built (sans the file extension, for example:
<tt>my-project-1.0.jar</tt>). It defaults to <tt>${artifactId}-${version}</tt>.
The term “finalName” is kind of a misnomer, however, as plugins
that build the bundled project have every right to ignore/modify this name (but
they usually do not). For example, if the <tt>maven-jar-plugin</tt> is
configured to give a jar a <tt>classifier</tt> of <tt>test</tt>, then the
actual jar defined above will be built as <tt>my-project-1.0-test.jar</tt>.</li>
-
-<li>
-<p><b>filter</b>: Defines <tt>*.properties</tt> files that contain a list of
properties that apply to resources which accept their settings (covered below).
In other words, the “<tt>name=value</tt>” pairs defined within
the filter files replace <tt>${name}</tt> strings within resources on build.
The example above defines the <tt>filter1.properties</tt> file under the
<tt>filter/</tt> directory. Maven’s default filter directory is
<tt>${basedir}/src/main/filters/</tt>.</p>
-<p>For a more comprehensive look at what filters are and what they can do,
take a look at the <a href="./guides/getting-started">quick start
guide</a>.</p></li>
-</ul>
+<li><b>directory</b>: This is the directory where the build will dump its
files or, in Maven parlance, the build's target. It aptly defaults to
<tt>${basedir}/target</tt>.</li>
+<li><b>finalName</b>: This is the name of the bundled project when it is
finally built (sans the file extension, for example:
<tt>my-project-1.0.jar</tt>). It defaults to <tt>${artifactId}-${version}</tt>.
The term "finalName" is kind of a misnomer, however, as plugins that
build the bundled project have every right to ignore/modify this name (but they
usually do not). For example, if the <tt>maven-jar-plugin</tt> is configured to
give a jar a <tt>classifier</tt> of <tt>test</tt>, then the actual jar defined
above will be built as <tt>my-project-1.0-test.jar</tt>.</li>
+<li><b>filter</b>: Defines <tt>*.properties</tt> files that contain a list of
properties that apply to resources which accept their settings (covered below).
In other words, the "<tt>name=value</tt>" pairs defined within the
filter files replace <tt>${name}</tt> strings within resources on build. The
example above defines the <tt>filter1.properties</tt> file under the
<tt>filter/</tt> directory. Maven's default filter directory is
<tt>${basedir}/src/main/filters/</tt>.
+<p>For a more comprehensive look at what filters are and what they can do,
take a look at the <a href="./guides/getting-started">quick start
guide</a>.</p></li></ul>
<div class="section">
-<h5><a name="Resources"></a>Resources</h5>
+<h5><a name="Resources">Resources</a></h5>
<p>Another feature of <tt>build</tt> elements is specifying where resources
exist within your project. Resources are not (usually) code. They are not
compiled, but are items meant to be bundled within your project or used for
various other reasons, such as code generation.</p>
<p>For example, a Plexus project requires a <tt>configuration.xml</tt> file
(which specifies component configurations to the container) to live within the
<tt>META-INF/plexus</tt> directory. Although we could just as easily place this
file within <tt>src/main/resource/META-INF/plexus</tt>, we want instead to give
Plexus its own directory of <tt>src/main/plexus</tt>. In order for the JAR
plugin to bundle the resource correctly, you would specify resources similar to
the following:</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -991,29 +794,17 @@ you with the given address.
</testResources>
...
</build>
-</project>
-</pre></div></div>
-
+</project></pre></div>
<ul>
-
<li><b>resources</b>: is a list of resource elements that each describe what
and where to include files associated with this project.</li>
-
<li><b>targetPath</b>: Specifies the directory structure to place the set of
resources from a build. Target path defaults to the base directory. A commonly
specified target path for resources that will be packaged in a JAR is
META-INF.</li>
-
-<li><b>filtering</b>: is <tt>true</tt> or <tt>false</tt>, denoting if
filtering is to be enabled for this resource. Note, that filter
<tt>*.properties</tt> files do not have to be defined for filtering to occur -
resources can also use properties that are by default defined in the POM (such
as \${project.version}), passed into the command line using the
“-D” flag (for example,
“<tt>-Dname</tt>=<tt>value</tt>”) or are explicitly defined by
the properties element. Filter files were covered above.</li>
-
-<li><b>directory</b>: This element’s value defines where the resources
are to be found. The default directory for a build is
<tt>${basedir}/src/main/resources</tt>.</li>
-
+<li><b>filtering</b>: is <tt>true</tt> or <tt>false</tt>, denoting if
filtering is to be enabled for this resource. Note, that filter
<tt>*.properties</tt> files do not have to be defined for filtering to occur -
resources can also use properties that are by default defined in the POM (such
as ${project.version}), passed into the command line using the "-D"
flag (for example, "<tt>-Dname</tt>=<tt>value</tt>") or are
explicitly defined by the properties element. Filter files were covered
above.</li>
+<li><b>directory</b>: This element's value defines where the resources are to
be found. The default directory for a build is
<tt>${basedir}/src/main/resources</tt>.</li>
<li><b>includes</b>: A set of files patterns which specify the files to
include as resources under that specified directory, using * as a wildcard.</li>
-
<li><b>excludes</b>: The same structure as <tt>includes</tt>, but specifies
which files to ignore. In conflicts between <tt>include</tt> and
<tt>exclude</tt>, <tt>exclude</tt> wins.</li>
-
-<li><b>testResources</b>: The <tt>testResources</tt> element block contains
<tt>testResource</tt> elements. Their definitions are similar to
<tt>resource</tt> elements, but are naturally used during test phases. The one
difference is that the default (Super POM defined) test resource directory for
a project is <tt>${basedir}/src/test/resources</tt>. Test resources are not
deployed.</li>
-</ul></div>
+<li><b>testResources</b>: The <tt>testResources</tt> element block contains
<tt>testResource</tt> elements. Their definitions are similar to
<tt>resource</tt> elements, but are naturally used during test phases. The one
difference is that the default (Super POM defined) test resource directory for
a project is <tt>${basedir}/src/test/resources</tt>. Test resources are not
deployed.</li></ul></div>
<div class="section">
-<h5><a name="Plugins"></a>Plugins</h5>
-
-<div class="source">
+<h5><a name="Plugins">Plugins</a></h5>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1036,22 +827,14 @@ you with the given address.
</plugin>
</plugins>
</build>
-</project>
-</pre></div></div>
+</project></pre></div>
<p>Beyond the standard coordinate of <tt>groupId:artifactId:version</tt>,
there are elements which configure the plugin or this builds interaction with
it.</p>
-
<ul>
-
<li><b>extensions</b>: <tt>true</tt> or <tt>false</tt>, whether or not to load
extensions of this plugin. It is by default false. Extensions are covered later
in this document.</li>
-
<li><b>inherited</b>: <tt>true</tt> or <tt>false</tt>, whether or not this
plugin configuration should apply to POMs which inherit from this one. Default
value is <tt>true</tt>.</li>
-
-<li>
-<p><b>configuration</b>: This is specific to the individual plugin. Without
going too in depth into the mechanics of how plugins work, suffice it to say
that whatever properties that the plugin Mojo may expect (these are getters and
setters in the Java Mojo bean) can be specified here. In the above example, we
are setting the classifier property to test in the
<tt>maven-jar-plugin</tt>’s Mojo. It may be good to note that all
configuration elements, wherever they are within the POM, are intended to pass
values to another underlying system, such as a plugin. In other words: values
within a <tt>configuration</tt> element are never explicitly required by the
POM schema, but a plugin goal has every right to require configuration
values.</p>
-<p>If your POM declares a parent, it will inherit plugin configuration from
either the <b>build/plugins</b> or <b>pluginManagement</b> sections of the
parent.</p>
+<li><b>configuration</b>: This is specific to the individual plugin. Without
going too in depth into the mechanics of how plugins work, suffice it to say
that whatever properties that the plugin Mojo may expect (these are getters and
setters in the Java Mojo bean) can be specified here. In the above example, we
are setting the classifier property to test in the <tt>maven-jar-plugin</tt>'s
Mojo. It may be good to note that all configuration elements, wherever they are
within the POM, are intended to pass values to another underlying system, such
as a plugin. In other words: values within a <tt>configuration</tt> element are
never explicitly required by the POM schema, but a plugin goal has every right
to require configuration values.
+<p>If your POM declares a parent, it will inherit plugin configuration from
either the <b>build/plugins</b> or <b>pluginManagement</b> sections of the
parent. </p>
<p>To illustrate, consider the following fragment from a parent POM:</p>
-
-<div class="source">
<div class="source">
<pre><plugin>
<groupId>my.group</groupId>
@@ -1065,11 +848,8 @@ you with the given address.
<parentKey>parent</parentKey>
</properties>
</configuration>
-</plugin>
-</pre></div></div>
+</plugin></pre></div>
<p>And consider the following plugin configuration from a project that uses
that parent as its parent:</p>
-
-<div class="source">
<div class="source">
<pre><plugin>
<groupId>my.group</groupId>
@@ -1081,12 +861,9 @@ you with the given address.
<properties>
<childKey>child</childKey>
</properties>
-</configuration>
-</pre></div></div>
+</configuration></pre></div>
<p>The default behavior is to merge the content of the <b>configuration</b>
element according to element name. If the child POM has a particular element,
that value becomes the effective value. if the child POM does not have an
element, but the parent does, the parent value becomes the effective value.
Note that this is purely an operation on XML; no code or configuration of the
plugin itself is involved. Only the elements, not their values, are
involved.</p>
<p>Applying those rules to the example, Maven comes up with:</p>
-
-<div class="source">
<div class="source">
<pre><plugin>
<groupId>my.group</groupId>
@@ -1099,12 +876,9 @@ you with the given address.
<childKey>child</childKey>
<parentKey>parent</parentKey>
</properties>
-</configuration>
-</pre></div></div>
+</configuration></pre></div>
<p>You can control how child POMs inherit configuration from parent POMs by
adding attributes to the children of the <b>configuration</b> element. The
attributes are <tt>combine.children</tt> and <tt>combine.self</tt>. Use these
attributes in a child POM to control how Maven combines plugin configuration
from the parent with the explicit configuration in the child.</p>
<p>Here is the child configuration with illustrations of the two
attributes:</p>
-
-<div class="source">
<div class="source">
<pre><configuration>
<items combine.children="append">
@@ -1115,11 +889,8 @@ you with the given address.
<!-- combine.self="merge" is the default -->
<childKey>child</childKey>
</properties>
-</configuration>
-</pre></div></div>
+</configuration></pre></div>
<p>Now, the effective result is the following:</p>
-
-<div class="source">
<div class="source">
<pre><configuration>
<items combine.children="append">
@@ -1130,20 +901,13 @@ you with the given address.
<properties combine.self="override">
<childKey>child</childKey>
</properties>
-</configuration>
-</pre></div></div>
-<p><b>combine.children=“append”</b> results in the concatenation
of parent and child elements, in that order.
<b>combine.self=“override”</b>, on the other hand, completely
suppresses parent configuration. You cannot use both both
<b>combine.self=“override”</b> and
<b>combine.children=“append”</b> on an element; if you try,
<i>override</i> will prevail.</p>
+</configuration></pre></div>
+<p><b>combine.children="append"</b> results in the concatenation of
parent and child elements, in that order.
<b>combine.self="override"</b>, on the other hand, completely
suppresses parent configuration. You cannot use both both
<b>combine.self="override"</b> and
<b>combine.children="append"</b> on an element; if you try,
<i>override</i> will prevail.</p>
<p>Note that these attributes only apply to the configuration element they are
declared on, and are not propagated to nested elements. That is if the content
of an <i>item</i> element from the child POM was a complex structure instead of
text, its sub-elements would still be subject to the default merge strategy
unless they were themselves marked with attributes.</p>
<p>The combine.* attributes are inherited from parent to child POMs. Take care
when adding those attributes a parent POM as this might affect child or
grand-child POMs.</p></li>
-
-<li>
-<p><b>dependencies</b>: Dependencies are seen a lot within the POM, and are an
element under all plugins element blocks. The dependencies have the same
structure and function as under that base build. The major difference in this
case is that instead of applying as dependencies of the project, they now apply
as dependencies of the plugin that they are under. The power of this is to
alter the dependency list of a plugin, perhaps by removing an unused runtime
dependency via <tt>exclusions</tt>, or by altering the version of a required
dpendency. See above under <b>Dependencies</b> for more information.</p></li>
-
-<li>
-<p><b>executions</b>: It is important to keep in mind that a plugin may have
multiple goals. Each goal may have a separate configuration, possibly even
binding a plugin’s goal to a different phase altogether.
<tt>executions</tt> configure the <tt>execution</tt> of a plugin’s
goals.</p>
+<li><b>dependencies</b>: Dependencies are seen a lot within the POM, and are
an element under all plugins element blocks. The dependencies have the same
structure and function as under that base build. The major difference in this
case is that instead of applying as dependencies of the project, they now apply
as dependencies of the plugin that they are under. The power of this is to
alter the dependency list of a plugin, perhaps by removing an unused runtime
dependency via <tt>exclusions</tt>, or by altering the version of a required
dpendency. See above under <b>Dependencies</b> for more information.</li>
+<li><b>executions</b>: It is important to keep in mind that a plugin may have
multiple goals. Each goal may have a separate configuration, possibly even
binding a plugin's goal to a different phase altogether. <tt>executions</tt>
configure the <tt>execution</tt> of a plugin's goals.
<p>For example, suppose you wanted to bind the <tt>antrun:run</tt> goal to the
<tt>verify</tt> phase. We want the task to echo the build directory, as well as
avoid passing on this configuration to its children (assuming it is a parent)
by setting <tt>inherited</tt> to <tt>false</tt>. You would get an
<tt>execution</tt> like this:</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1174,30 +938,16 @@ you with the given address.
</plugin>
</plugins>
</build>
-</project>
-</pre></div></div></li>
-
-<li>
-<p><b>id</b>: Self explanatory. It specifies this execution block between all
of the others. When the phase is run, it will be shown in the form:
<tt>[plugin:goal execution: id]</tt>. In the case of this example:
<tt>[antrun:run execution: echodir]</tt></p></li>
-
+</project></pre></div></li>
+<li><b>id</b>: Self explanatory. It specifies this execution block between all
of the others. When the phase is run, it will be shown in the form:
<tt>[plugin:goal <a name="execution:_id">execution: id</a>]</tt>. In the case
of this example: <tt>[antrun:run <a name="execution:_echodir">execution:
echodir</a>]</tt></li>
<li><b>goals</b>: Like all pluralized POM elements, this contains a list of
singular elements. In this case, a list of plugin <tt>goals</tt> which are
being specified by this <tt>execution</tt> block.</li>
-
<li><b>phase</b>: This is the phase that the list of goals will execute in.
This is a very powerful option, allowing one to bind any goal to any phase in
the build lifecycle, altering the default behavior of Maven.</li>
-
<li><b>inherited</b>: Like the <tt>inherited</tt> element above, setting this
false will supress Maven from passing this execution onto its children. This
element is only meaningful to parent POMs.</li>
-
-<li><b>configuration</b>: Same as above, but confines the configuration to
this specific list of goals, rather than all goals under the plugin.</li>
-</ul></div>
+<li><b>configuration</b>: Same as above, but confines the configuration to
this specific list of goals, rather than all goals under the
plugin.</li></ul></div>
<div class="section">
-<h5><a name="Plugin_Management"></a>Plugin Management</h5>
-
+<h5><a name="Plugin_Management">Plugin Management</a></h5>
<ul>
-
-<li><b>pluginManagement</b>: is an element that is seen along side plugins.
Plugin Management contains plugin elements in much the same way, except that
rather than configuring plugin information for this particular project build,
it is intended to configure project builds that inherit from this one. However,
this only configures plugins that are actually referenced within the plugins
element in the children. The children have every right to override
<tt>pluginManagement</tt> definitions.</li>
-</ul>
-<!-- -->
-
-<div class="source">
+<li><b>pluginManagement</b>: is an element that is seen along side plugins.
Plugin Management contains plugin elements in much the same way, except that
rather than configuring plugin information for this particular project build,
it is intended to configure project builds that inherit from this one. However,
this only configures plugins that are actually referenced within the plugins
element in the children. The children have every right to override
<tt>pluginManagement</tt> definitions.</li></ul>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1229,11 +979,8 @@ you with the given address.
</pluginManagement>
...
</build>
-</project>
-</pre></div></div>
+</project></pre></div>
<p>If we added these specifications to the plugins element, they would apply
only to a single POM. However, if we apply them under the
<tt>pluginManagement</tt> element, then this POM <i>and all inheriting POMs</i>
that add the <tt>maven-jar-plugin</tt> to the build will get the
<tt>pre-process-classes</tt> execution as well. So rather than the above mess
included in every child <tt>pom.xml</tt>, only the following is required:</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1250,16 +997,13 @@ you with the given address.
</plugins>
...
</build>
-</project>
-</pre></div></div></div></div>
+</project></pre></div></div></div>
<div class="section">
-<h4><a name="The_Build_Element_Set"></a>The Build Element Set</h4>
-<p>The <tt>Build</tt> type in the XSD denotes those elements that are
available only for the “project build”. Despite the number of
extra elements (six), there are really only two groups of elements that project
build contains that are missing from the profile build: directories and
extensions.</p>
+<h4><a name="The_Build_Element_Set"></a>The <a name="Build_Element">Build
Element</a> Set</h4>
+<p>The <tt>Build</tt> type in the XSD denotes those elements that are
available only for the "project build". Despite the number of extra
elements (six), there are really only two groups of elements that project build
contains that are missing from the profile build: directories and
extensions.</p>
<div class="section">
-<h5><a name="Directories"></a>Directories</h5>
+<h5><a name="Directories">Directories</a></h5>
<p>The set of directory elements live in the parent build element, which set
various directory structures for the POM as a whole. Since they do not exist in
profile builds, these cannot be altered by profiles.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1274,14 +1018,11 @@ you with the given address.
<testOutputDirectory>${basedir}/target/test-classes</testOutputDirectory>
...
</build>
-</project>
-</pre></div></div>
+</project></pre></div>
<p>If the values of a <tt>*Directory</tt> element above is set as an absolute
path (when their properties are expanded) then that directory is used.
Otherwise, it is relative to the base build directory:
<tt>${basedir}</tt>.</p></div>
<div class="section">
-<h5><a name="Extensions"></a>Extensions</h5>
-<p>Extensions are a list of artifacts that are to be used in this build. They
will be included in the running build’s classpath. They can enable
extensions to the build process (such as add an ftp provider for the Wagon
transport mechanism), as well as make plugins active which make changes to the
build lifecycle. In short, extensions are artifacts that activated during
build. The extensions do not have to actually do anything nor contain a Mojo.
For this reason, extensions are excellent for specifying one out of multiple
implementations of a common plugin interface.</p>
-
-<div class="source">
+<h5><a name="Extensions">Extensions</a></h5>
+<p>Extensions are a list of artifacts that are to be used in this build. They
will be included in the running build's classpath. They can enable extensions
to the build process (such as add an ftp provider for the Wagon transport
mechanism), as well as make plugins active which make changes to the build
lifecycle. In short, extensions are artifacts that activated during build. The
extensions do not have to actually do anything nor contain a Mojo. For this
reason, extensions are excellent for specifying one out of multiple
implementations of a common plugin interface.</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1299,14 +1040,11 @@ you with the given address.
</extensions>
...
</build>
-</project>
-</pre></div></div></div></div></div>
+</project></pre></div></div></div></div>
<div class="section">
-<h3><a name="Reporting"></a>Reporting</h3>
-<p>Reporting contains the elements that correspond specifically for the
<tt>site</tt> generation phase. Certain Maven plugins can generate reports
defined and configured under the reporting element, for example: generating
Javadoc reports. Much like the build element’s ability to configure
plugins, reporting commands the same ability. The glaring difference is that
rather than fine-grained control of plug-in goals within the executions block,
reporting configures goals within <tt>reportSet</tt> elements. And the subtler
difference is that a plugin <tt>configuration</tt> under the <tt>reporting</tt>
element works as <tt>build</tt> plugin <tt>configuration</tt>, although the
opposite is not true (a <tt>build</tt> plugin <tt>configuration</tt> does not
affect a <tt>reporting</tt> plugin).</p>
+<h3><a name="Reporting">Reporting</a></h3>
+<p>Reporting contains the elements that correspond specifically for the
<tt>site</tt> generation phase. Certain Maven plugins can generate reports
defined and configured under the reporting element, for example: generating
Javadoc reports. Much like the build element's ability to configure plugins,
reporting commands the same ability. The glaring difference is that rather than
fine-grained control of plug-in goals within the executions block, reporting
configures goals within <tt>reportSet</tt> elements. And the subtler difference
is that a plugin <tt>configuration</tt> under the <tt>reporting</tt> element
works as <tt>build</tt> plugin <tt>configuration</tt>, although the opposite is
not true (a <tt>build</tt> plugin <tt>configuration</tt> does not affect a
<tt>reporting</tt> plugin).</p>
<p>Possibly the only item under the <tt>reporting</tt> element that would not
be familiar to someone who understood the <tt>build</tt> element is the Boolean
<tt>excludeDefaults</tt> element. This element signifies to the site generator
to exclude reports normally generated by default. When a site is generated via
the <tt>site</tt> build cycle, a <i>Project Info</i> section is placed in the
left-hand menu, chock full of reports, such as the <b>Project Team</b> report
or <b>Dependencies</b> list report. These report goals are generated by
<tt>maven-project-info-reports-plugin</tt>. Being a plugin like any other, it
may also be suppressed in the following, more verbose, way, which effectively
turns off project-info reports.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1326,15 +1064,12 @@ you with the given address.
</plugins>
</reporting>
...
-</project>
-</pre></div></div>
+</project></pre></div>
<p>The other difference is the <tt>outputDirectory</tt> element under
<tt>plugin</tt>. In the case of reporting, the output directory is
<tt>${basedir}/target/site</tt> by default.</p>
<div class="section">
-<h4><a name="Report_Sets"></a>Report Sets</h4>
-<p>It is important to keep in mind that an individual plugin may have multiple
goals. Each goal may have a separate configuration. Report sets configure
execution of a report plugin’s goals. Does this sound familiar -
deja-vu? The same thing was said about build’s <tt>execution</tt>
element with one difference: you cannot bind a report to another phase.
Sorry.</p>
-<p>For example, suppose you wanted to configure the <tt>javadoc:javadoc</tt>
goal to link to “<a class="externalLink"
href="http://java.sun.com/j2se/1.5.0/docs/api/";>http://java.sun.com/j2se/1.5.0/docs/api/</a>”,
but only the <tt>javadoc</tt> goal (not the goal
<tt>maven-javadoc-plugin:jar</tt>). We would also like this configuration
passed to its children, and set <tt>inherited</tt> to true. The
<tt>reportSet</tt> would resemble the following:</p>
-
-<div class="source">
+<h4><a name="Report_Sets">Report Sets</a></h4>
+<p>It is important to keep in mind that an individual plugin may have multiple
goals. Each goal may have a separate configuration. Report sets configure
execution of a report plugin's goals. Does this sound familiar - deja-vu? The
same thing was said about build's <tt>execution</tt> element with one
difference: you cannot bind a report to another phase. Sorry.</p>
+<p>For example, suppose you wanted to configure the <tt>javadoc:javadoc</tt>
goal to link to "<a class="externalLink"
href="http://java.sun.com/j2se/1.5.0/docs/api/";>http://java.sun.com/j2se/1.5.0/docs/api/</a>",
but only the <tt>javadoc</tt> goal (not the goal
<tt>maven-javadoc-plugin:jar</tt>). We would also like this configuration
passed to its children, and set <tt>inherited</tt> to true. The
<tt>reportSet</tt> would resemble the following:</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1363,27 +1098,18 @@ you with the given address.
</plugins>
</reporting>
...
-</project>
-</pre></div></div>
+</project></pre></div>
<p>Between build <tt>executions</tt> and reporting <tt>reportSets</tt>, it
should be clear now as to why they exist. In the simplest sense, they drill
down in configuration. The POM must have a way not only to configure plugins,
but they also must configure individual goals of those plugins. That is where
these elements come in, giving the POM ultimate granularity in control of its
build destiny.</p></div></div></div>
<div class="section">
-<h2><a name="More_Project_Information"></a>More Project Information</h2>
-<p>Although the above information is enough to get a firm grasp on POM
authoring, there are far more elements to make developer’s live easier.
Many of these elements are related to site generation, but like all POM
declarations, they may be used for anything, depending upon how certain plugins
use it. The following are the simplest elements:</p>
-
+<h2><a name="More_Project_Information">More Project Information</a></h2>
+<p>Although the above information is enough to get a firm grasp on POM
authoring, there are far more elements to make developer's live easier. Many of
these elements are related to site generation, but like all POM declarations,
they may be used for anything, depending upon how certain plugins use it. The
following are the simplest elements:</p>
<ul>
-
-<li><b>name</b>: Projects tend to have conversational names, beyond the
<tt>artifactId</tt>. The Sun engineers did not refer to their project as
“java-1.5”, but rather just called it “Tiger”. Here
is where to set that value.</li>
-
+<li><b>name</b>: Projects tend to have conversational names, beyond the
<tt>artifactId</tt>. The Sun engineers did not refer to their project as
"java-1.5", but rather just called it "Tiger". Here is
where to set that value.</li>
<li><b>description</b>: Description of a project is always good. Although this
should not replace formal documentation, a quick comment to any readers of the
POM is always helpful.</li>
-
<li><b>url</b>: The URL, like the name, is not required. This is a nice
gesture for projects users, however, so that they know where the project
lives.</li>
-
-<li><b>inceptionYear</b>: This is another good documentation point. It will at
least help you remember where you have spent the last few years of your
life.</li>
-</ul>
+<li><b>inceptionYear</b>: This is another good documentation point. It will at
least help you remember where you have spent the last few years of your
life.</li></ul>
<div class="section">
-<h3><a name="Licenses"></a>Licenses</h3>
-
-<div class="source">
+<h3><a name="Licenses">Licenses</a></h3>
<div class="source">
<pre><licenses>
<license>
@@ -1392,21 +1118,14 @@ you with the given address.
<distribution>repo</distribution>
<comments>A business-friendly OSS license</comments>
</license>
-</licenses>
-</pre></div></div>
-<p>Licenses are legal documents defining how and when a project (or parts of a
project) may be used. Note that a project should list only licenses that may
apply directly to this project, and not list licenses that apply to this
project’s dependencies. Maven currently does little with these documents
other than displays them on generated sites. However, there is talk of flexing
for different types of licenses, forcing users to accept license agreements for
certain types of (non open source) projects.</p>
-
+</licenses></pre></div>
+<p>Licenses are legal documents defining how and when a project (or parts of a
project) may be used. Note that a project should list only licenses that may
apply directly to this project, and not list licenses that apply to this
project's dependencies. Maven currently does little with these documents other
than displays them on generated sites. However, there is talk of flexing for
different types of licenses, forcing users to accept license agreements for
certain types of (non open source) projects.</p>
<ul>
-
<li><b>name</b>, <b>url</b> and <b>comments</b>: are self explanatory, and
have been encountered before in other capacities. The fourth license element
is:</li>
-
-<li><b>distribution</b>: This describes how the project may be legally
distributed. The two stated methods are repo (they may be downloaded from a
Maven repository) or manual (they must be manually installed).</li>
-</ul></div>
+<li><b>distribution</b>: This describes how the project may be legally
distributed. The two stated methods are repo (they may be downloaded from a
Maven repository) or manual (they must be manually installed).</li></ul></div>
<div class="section">
-<h3><a name="Organization"></a>Organization</h3>
+<h3><a name="Organization">Organization</a></h3>
<p>Most projects are run by some sort of organization (business, private
group, etc.). Here is where the most basic information is set.</p>
-
-<div class="source">
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1417,13 +1136,10 @@ you with the given address.
<name>Codehaus Mojo</name>
<url>http://mojo.codehaus.org</url>
</organization>
-</project>
-</pre></div></div></div>
+</project></pre></div></div>
<div class="section">
-<h3><a name="Developers"></a>Developers</h3>
-<p>All projects consist of files that were created, at some time, by a person.
Like the other systems that surround a project, so to do the people involved
with a project have a stake in the project. Developers are presumably members
of the project’s core development. Note that, although an organization
may have many developers (programmers) as members, it is not good form to list
them all as developers, but only those who are immediately responsible for the
code. A good rule of thumb is, if the person should not be contacted about the
project, they need not be listed here.</p>
-
-<div class="source">
+<h3><a name="Developers">Developers</a></h3>
+<p>All projects consist of files that were created, at some time, by a person.
Like the other systems that surround a project, so to do the people involved
with a project have a stake in the project. Developers are presumably members
of the project's core development. Note that, although an organization may have
many developers (programmers) as members, it is not good form to list them all
as developers, but only those who are immediately responsible for the code. A
good rule of thumb is, if the person should not be contacted about the project,
they need not be listed here.</p>
<div class="source">
<pre><project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1449,26 +1165,16 @@ you with the given address.
</developer>
</developers>
...
-</project>
-</pre></div></div>
-
+</project></pre></div>
<ul>
-
-<li><b>id</b>, <b>name</b>, <b>email</b>: These corrospond to the
developer’s ID (presumably some unique ID across an organization), the
developer’s name and email address.</li>
-
-<li><b>organization</b>, <b>organizationUrl</b>: As you probably guessed,
these are the developer’s organization name and it’s URL,
respectively.</li>
-
+<li><b>id</b>, <b>name</b>, <b>email</b>: These corrospond to the developer's
ID (presumably some unique ID across an organization), the developer's name and
email address.</li>
+<li><b>organization</b>, <b>organizationUrl</b>: As you probably guessed,
these are the developer's organization name and it's URL, respectively.</li>
<li><b>roles</b>: A <tt>role</tt> should specify the standard actions that the
person is responsible for. Like a single person can wear many hats, a single
person can take on multiple <tt>roles</tt>.</li>
-
-<li><b>timezone</b>: A numerical offset in hours from GMT where the developer
lives or a valid <a class="externalLink"
href="http://google-web-toolkit.googlecode.com/svn/javadoc/2.0/com/google/gwt/i18n/client/constants/TimeZoneConstants.html";>time
zone id</a> like “America/Montreal” (UTC-05:00) or
“Europe/Paris” (UTC+01:00).</li>
-
-<li><b>properties</b>: This element is where any other properties about the
person goes. For example, a link to a personal image or an instant messenger
handle. Different plugins may use these properties, or they may simply be for
other developers who read the POM.</li>
-</ul></div>
+<li><b>timezone</b>: A numerical offset in hours from GMT where the developer
lives or a valid <a class="externalLink"
href="http://google-web-toolkit.googlecode.com/svn/javadoc/2.0/com/google/gwt/i18n/client/constants/TimeZoneConstants.html";>time
zone id</a> like "America/Montreal" (UTC-05:00) or
"Europe/Paris" (UTC+01:00). </li>
[... 355 lines stripped ...]
