|
|
Maven utilizes an XML project descriptor to generate an object
model for a project. This object model can then be manipulated
using an interface to the Maven. Currently, the only interface
provided is via Ant build files.
In the future, other interfaces may be provided such as a CLI or
JMX. This document describes the valid XML elements and
attributes that constitute a Maven project descriptor.
For reference, the XML schema used to validate the project
descriptor is available in the CVS
Repository. In addition, a sample project descriptor is
presented in the Integration
document and there is visual representation of the project descriptor
here. For those wondering,
yes, Maven's build system is built by Maven (we believe in eating our own dog food :)
The <project> element specifies various
attributes about a project. This is the root element of the
project descriptor. The following table lists all of the
possible child elements. Child elements with children are then
documented further in subsequent sections.
|
Element
|
Description
|
|
name
|
The full name of the project. This value is used when
generating JavaDoc
titles.
|
|
id
|
The short name of the project. This value is used when
naming jars and distribution files.
|
|
pomVersion
|
The current version of the Maven project descriptor. This
version number enables Maven to automatically update an
out-of-date project descriptor when a new version is
available. This version number should not be changed after
the descriptor has been created. Maven will update it
automatically. Please refer to the Updating document for more
information.
|
|
currentVersion
|
The current version of the project. This value is used when
naming jars and distribution files.
|
|
organization
|
The organization to which the project belongs. This element
describes various attributes of the organization.
|
|
inceptionYear
|
The year of the project's inception specified with 4 digits.
This value is used when generating JavaDoc copyright
notices.
|
|
package
|
The Java package name of the project. This value is used
when generating JavaDoc.
|
|
gumpRepositoryId
|
Optional. This is the Id of the Gump repository that this project is
part of (assuming it participates in the Gump integration
effort).
|
|
shortDescription
|
A short description of the project. The short description
should be limited to a single line.
|
|
description
|
Optional. A detailed description of the project. This element is
usually specified as CDATA to enable the use of HTML tags
within the description. This description is used to
generate the front page
of the site's web site.
|
|
url
|
The URL to the project's homepage.
|
|
logo
|
The URL to the project's logo image. This can be an URL relative
to the base directory of the generated web site,
(e.g., /images/project-logo.png) or an absolute URL
(e.g., http://my.corp/project-logo.png). This is used
when generating the project documentation.
|
|
issueTrackingUrl
|
Optional. The URL to the project's issue tracking system.
|
|
siteAddress
|
Optional. The hostname of the web server that hosts the project's web
site. This is used when the web site is deployed.
|
|
siteDirectory
|
Optional. The directory on the web server where the public web site
for this project resides. This is used when the web site is deployed.
|
|
distributionDirectory
|
Optional. The directory on the web server where the final
distributions will be published. This is used when the
distributions are
deployed.
|
|
repository
|
Information relating to the source configuration
management system used by this project.
|
|
versions
|
Optional. Contains information on previous versions of the
project. This information is used when invoking the maven:dist
target.
|
|
mailingLists
|
Contains information about a project's mailing lists. This
is used to generate the front
page of the site's web site.
|
|
developers
|
Describes the committers to a project. This is used to
generate the Project Team
page of the project's web site.
|
|
contributors
|
Describes the contributors to a project. This is used to generate
the Project Team page of
the project's web site.
|
|
dependencies
|
Describes the dependencies to a project. This is used to
when building a project.
|
|
build
|
Describes the build environment of a project. This is used
when invoking the build system.
|
This element describes various attributes of the organziation to
which the project belongs. These attributes are utilized when
documentation is created (for copyright notices and links).
|
Element
|
Description
|
|
name
|
The full name of the organization.
|
|
url
|
The URL to the organization's home page.
|
|
logo
|
The URL to the organization's logo image. This can be an URL relative
to the base directory of the generated web site,
(e.g., /images/org-logo.png) or an absolute URL
(e.g., http://my.corp/logo.png). This value is used
when generating the project documentation.
|
|
Element
|
Description
|
|
connection
|
Optional. The source configuration management system URL
that describes the repository and how to connect to the
repository. This is used by Maven when building versions
from specific ID.
The format of this element is as follows:
scm:<provider>:<provider-parameters>
For cvs, the format should be:
scm:cvs:pserver:user@host:/cvs/root:module-name
Where pserver is the protocol used to access CVS,
user@host is the user name to log in to the specified
cvs host, /cvs/root is the cvs root
directory, and module-name is the name of the cvs
module to be worked on
As an example, the settings for an Apache project are usually:
scm:cvs:pserver:anoncvs@cvs.apache.org:/home/cvspublic:module-name
Currently CVS is the only supported scm. Others will be added
as soon as possible
|
|
url
|
Optional. The URL to the project's browsable CVS repository
|
This element describes each of the previous versions of the
project. Each version is described by a version
element
|
Element
|
Description
|
|
id
|
A unique identifier for a version. This ID is
used to specify the version that maven:dist
builds.
|
|
name
|
The external version number under which this
release was distributed. Examples include:
1.0, 1.1-alpha1,
1.2-beta, 1.3.2 etc.
|
|
tag
|
The name given in the version control system
(e.g. cvs) used by the project for the source
code associated with this version of the
project.
|
This element describes all of the mailing lists associated with
a project. Each mailing list is described by a
mailingList element, which is then described by
additional elements (described below). The auto-generated site
documentation references this information.
|
Element
|
Description
|
|
name
|
The name of the mailing list.
|
|
subscribe
|
The email address or link that can be used to subscribe to the
mailing list. If this is an email address, a
mailto: link will automatically be created
when the documentation is created.
|
|
unsubscribe
|
The email address or link that can be used to unsubscribe to
the mailing list. If this is an email address, a
mailto: link will automatically be created
when the documentation is created.
|
|
archive
|
The link to a URL that can browse the archive.
|
This element describes all of the developers associated with a
project. Each developer is described by a
developer element, which is then described by
additional elements (described below). The auto-generated site
documentation references this information.
|
Element
|
Description
|
|
name
|
The full name of the developer.
|
|
id
|
The username of the developer.
|
|
email
|
The email address of the developer.
|
|
organization
|
The organization to which the developer belongs.
|
|
roles
|
The roles the developer plays in the project. Each role is
describe by a role element, the body of which is a
role name.
|
This element describes all of the contributors associated with a
project who are not developers. Each contributor is described by a
contributor element, which is then describe by additional
elements (described below). The auto-generated site documentation
references this information.
|
Element
|
Description
|
|
name
|
The full name of the contributor.
|
|
email
|
The email address of the contributor.
|
|
organization
|
The organization to which the contributor belongs.
|
|
roles
|
The roles the contributor plays in the project. Each role is
describe by a role element, the body of which is a
role name.
|
This element describes all of the dependencies associated with a
project. Each dependency is described by a
dependency element, which is then described by
additional elements (described below). These dependencies are
used to construct a classpath for your project during the build
process. In addition, Maven can automatically download these
dependencies from a central repository. The filename that Maven
downloads from the repository is id-version.jar
where id corresponds to the id
element and version corresponds to the
version element.
|
Element
|
Description
|
|
id
|
The name of the dependency.
|
|
version
|
The version of the dependency.
|
|
url
|
The url of the dependency's homepage.
|
This element describes all of the build properties associated
with a project. There are several elements that describe a
project's build environment. Each one is described below:
|
Element
|
Description
|
|
name
|
The full name of the project. This value is used when
generating JavaDoc
titles.
|
|
nagEmailAddress
|
An address to which notifications regarding the status of builds
for this project can be sent. This is intended for use by tools
which do unattended builds, for example those providing for
continuous integration. Currently this is used by the
maven:gump-descriptor
target.
|
|
unitTestSourceDirectory
|
This element specifies a directory containing the unit test
source of the project. The generated build system will
compile these directories when the project is being tested.
The unit tests must use the JUnit test framework.
|
|
integrationUnitTestSourceDirectory
|
This element specifies a directory containing the
integration unit test source of the project. The generated
build system will compile these directories when the project
is being tested. The integration unit tests must use the
Cactus test framework.
|
|
sourceDirectory
|
This element specifies a directory containing the source
of the project. The generated build system will compile
the source in this directory when the project is built.
|
|
aspectSourceDirectory
|
This element specifies a directory containing Aspect
sources of the project. The generated build system will
compile the Aspects in this directory when the project is
built if Aspects have been enabled (see the Properties document).
|
|
jarResources
|
This element specifies any additional resources that should
be packaged up inside the JAR file. Each resource is
specified by a jarResource element.
|
|
jars
|
This element specifies the additional JARs that should be
packaged as part of the final JAR. [TODO: not quite sure how
this is different than jarResources, need further
clarification.] Each additional JAR is specified by a
jar element.
|
|
unitTestPatterns
|
This element specifies the Java source file patterns to
indicate which files are unit tests in the
unitTestSourceDirectory. Each pattern is
specified by a unitTestPattern element.
|
|
integrationUnitTestPatterns
|
This element specifies the Java source file patterns to
indicate which files are integration unit tests in the
integrationUnitTestSourceDirectory. Each
pattern is specified by a
integrationUnitTestPattern element.
|
|
Element
|
Description
|
|
jarResource
|
The pattern specifying the resource to be packaged in the
JAR file created by the maven:jar target. This
value can be either: include = AntPattern,
exclude = AntPattern, or a JAR descriptor
file. The path name is relative to
${basedir} unless it has been overridden via
the
${maven.jarResources.basedir} property.
|
|
Element
|
Description
|
|
unitTestPattern
|
The pattern specifying a set of Java source files. This
value can be either: include = AntPattern,
exclude = AntPattern, or a JAR descriptor
file. Note: these patterns specify .java
sources and not .class files. These unit
tests must use the JUnit testing framework.
|
|
Element
|
Description
|
|
integrationUnitTestPattern
|
The pattern specifying a set of Java source files. This
value can be either: include = AntPattern,
exclude = AntPattern, or a JAR descriptor
file. Note: these patterns specify .java
sources and not .class files. These unit
tests must use the Cactus
testing framework.
|
|
Element
|
Description
|
|
jar
|
A JAR that should be packaged in the project's JAR. This
can be used to package additional JAR files with your
project. The JAR is relative to ${basedir}
if an absolute path is not used.
|
|
