This is a reference for the Maven project descriptor used in Maven.
An XSD is available at:
<project> <extend/> <pomVersion/> <id/> <groupId/> <artifactId/> <name/> <currentVersion/> <shortDescription/> <description/> <url/> <logo/> <issueTrackingUrl/> <inceptionYear/> <gumpRepositoryId/> <siteAddress/> <siteDirectory/> <distributionSite/> <distributionDirectory/> <mailingLists> <mailingList> <name/> <subscribe/> <unsubscribe/> <post/> <archive/> <otherArchives/> </mailingList> </mailingLists> <developers> <developer> <id/> <name/> <email/> <url/> <organization/> <organizationUrl/> <roles/> <timezone/> <properties/> </developer> </developers> <contributors> <contributor> <name/> <email/> <url/> <organization/> <organizationUrl/> <roles/> <timezone/> <properties/> </contributor> </contributors> <licenses> <license> <name/> <url/> <distribution/> <comments/> </license> </licenses> <versions> <version> <name/> <tag/> <id/> </version> </versions> <branches> <branch> <tag/> </branch> </branches> <packageGroups> <packageGroup> <title/> <packages/> </packageGroup> </packageGroups> <reports/> <repository> <connection/> <developerConnection/> <url/> </repository> <organization> <name/> <url/> <logo/> </organization> <properties/> <package/> <build> <nagEmailAddress/> <sourceDirectory/> <unitTestSourceDirectory/> <aspectSourceDirectory/> <integrationUnitTestSourceDirectory/> <sourceModifications> <sourceModification> <className/> <property/> <directory/> <includes/> <excludes/> </sourceModification> </sourceModifications> <unitTest> <resources> <resource> <targetPath/> <filtering/> <directory/> <includes/> <excludes/> </resource> </resources> <includes/> <excludes/> </unitTest> <defaultGoal/> <resources> <resource> <targetPath/> <filtering/> <directory/> <includes/> <excludes/> </resource> </resources> </build> <dependencies> <dependency> <id/> <groupId/> <artifactId/> <version/> <url/> <jar/> <type/> <properties/> </dependency> </dependencies> </project>
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 |
---|---|
extend
|
The location of the parent project, if one exists. Values from the
parent project will be the default for this project if they are
left unspecified. The path may be absolute, or relative to the
current project.xml file.
<extend>${basedir}/../project.xml</extend> |
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. |
id
|
The short name of the project. This value is used when naming jars and distribution files. |
groupId
|
The short name of the project group. This value is used to group all jars for a project in one directory. For more info look at the user guide. |
artifactId
|
The short name of the project. This value is used in conjunction
with groupId
when naming jars and
distribution files.
|
name
|
The full name of the project. This value is used when generating JavaDoc titles. |
currentVersion
|
The current version of the project. This value is used when naming jars and distribution files. |
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 description is used as the default to generate the
Mailing Lists
of the project's
web site, and is shown when maven --usage is called on
the project. While this element can be specified as CDATA to enable
the use of HTML tags within the description, you are encouraged to
provide an alternative home page using xdocs/index.xml
if this is required.
|
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. |
inceptionYear
|
The year of the project's inception specified with 4 digits. This value is used when generating JavaDoc copyright notices. |
gumpRepositoryId
|
Optional. This is the Id of the Gump repository that this project is part of (assuming it participates in the Gump integration effort). |
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. |
distributionSite
|
Optional. The server server where the final
distributions will be published. This is used when the
distributions are
deployed.
If this isn't defined, the central repository is used instead as
determined by |
distributionDirectory
|
Optional. The directory on the web server where the final distributions will be published. This is used when the distributions are deployed. |
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. |
licenses
|
This element describes all of the licenses for this project.
Each license is described by a license element, which
is then described by additional elements (described below). The
auto-generated site documentation references this information.
Projects should only list the license(s) that applies to the project
and not the licenses that apply to dependencies.
|
versions
|
Optional. Contains information on previous versions of the
project. This information is used when invoking the
maven:dist
target.
|
branches
|
Optional. Contains information on branches of the
project. This information is used when invoking the
maven:dist
target.
|
packageGroups
|
Package groups required for complete javadocs. |
reports
|
|
repository
|
Specification for the SCM used by the project. |
organization
|
This element describes various attributes of the organization to which the project belongs. These attributes are utilized when documentation is created (for copyright notices and links). |
properties
|
Project properties that will be used by various plugins |
package
|
The Java package name of the project. This value is used when generating JavaDoc. |
build
|
Information required to build the project. |
dependencies
|
This element describes all of the dependencies associated with a
project. Each dependency is described by a
These dependencies are used to construct a classpath for your project during the build process. Maven can automatically download these dependencies from a remote repository.
The filename that Maven downloads from the repository is
When Maven goes looking for a dependency in the remote repository, it uses the dependency element to construct the URL to download from. This URL is defined as: ${repo}/${groupId}/${type}s/${artifactId}-${version}.${type} Where
|
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.
|
post
|
The email address or link that can be used to post 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 where you can browse the mailing list archive. |
otherArchives
|
The link to other URLs where you can browse the list archive. |
Information about one of the committers on this project. Derived from
Contributor
.
Element | Description |
---|---|
id
|
The username of the developer. |
name
|
The full name of the contributor. |
email
|
The email address of the contributor. |
url
|
The URL for the homepage of the contributor. |
organization
|
The organization to which the contributor belongs. |
organizationUrl
|
The URL of the organization. |
roles
|
The roles the contributor plays in the project. Each role is
described by a role element, the body of which is a
role name.
|
timezone
|
The timezone the contributor is in. This is a number in the range -11 to 12. |
properties
|
Properties about the contributor, such as an instant messenger handle. |
Description of a person who has contributed to the project, but who does not have commit privileges. Usually, these contributions come in the form of patches submitted.
Element | Description |
---|---|
name
|
The full name of the contributor. |
email
|
The email address of the contributor. |
url
|
The URL for the homepage of the contributor. |
organization
|
The organization to which the contributor belongs. |
organizationUrl
|
The URL of the organization. |
roles
|
The roles the contributor plays in the project. Each role is
described by a role element, the body of which is a
role name.
|
timezone
|
The timezone the contributor is in. This is a number in the range -11 to 12. |
properties
|
Properties about the contributor, such as an instant messenger handle. |
Describes the licenses for this project. This is used to generate the License page of the project's web site. Typically the licenses listed for the project are that of the project itself, and not of dependencies.
Element | Description |
---|---|
name
|
The full legal name of the license. |
url
|
The official url for the license text. |
distribution
|
The primary method by which this project may be distributed.
|
comments
|
Addendum information pertaining to this license. |
This element describes each of the previous versions of the
project. Each version is described by a version
element
Element | Description |
---|---|
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. |
id
|
A unique identifier for a version. This ID is
used to specify the version that
maven:dist
builds.
|
Optional. Contains information on branches of the project. This
information is used when invoking the
maven:dist
target.
Element | Description |
---|---|
tag
|
The branch tag in the version control system (e.g. cvs) used by the project for the source code associated with this branch of the project. |
Javadoc allows related packages to be gathered together into logical 'groups'. Groups of packages appear under a common subheading in the javadoc overview documentation.
Element | Description |
---|---|
title
|
The title that appears as a subheading in the javadoc overview page. |
packages
|
The packages that should be grouped together. |
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><delimiter><provider-parameters> where For cvs, the format for pserver repositories should be: scm:cvs:pserver:user@host:/cvs/root:module-name For local networked repositories (eg. pserver to local machine) scm:cvs:lserver:user@host:/cvs/root:module-name For ssh access: scm:cvs:ext:user@host:/cvs/root:module-name CVS_RSH to be set, typically to ssh or your
ssh client.
Some cvs clients support other protocols, such as ntserver and extssh. Here's an example using CVS NT and ntserver: scm:cvs|ntserver|user@server|e:\cvs|Deployment : ) in it.
For local file system repositories scm:cvs:local:ignored:/cvs/root:module-name For StarTeam access: scm:starteam:username:password@host:port/project/view/folder
The delimiter is determined by the character after "scm". eg.
Where As an example, the settings for an Apache project are usually: scm:cvs:pserver:anoncvs@cvs.apache.org:/home/cvspublic:module-name Currently CVS, Starteam and SubVersion are the only supported scm's. Others will be added as soon as possible |
developerConnection
|
Just like connection, but for developers, i.e. this scm connection will not be read only. |
url
|
The URL to the project's browsable CVS repository. |
Specifies the organization who produces this project.
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 |
---|---|
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 gump plugin target. |
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. The path given is relative to the project descriptor. |
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. The path given is relative to the project descriptor. |
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 Aspectj goals document). The path given is relative to the project descriptor. |
integrationUnitTestSourceDirectory
|
This element specifies a directory containing integration test sources of the project. |
sourceModifications
|
This element describes all of the sourceModifications associated
with a project. Each source modification is described by a
sourceModification element, which is then described by
additional elements (described below). These modifications are used
to exclude or include various source depending on the environment
the build is running in.
|
unitTest
|
This element specifies unit tests associated with the project. |
defaultGoal
|
The default goal (or phase in Maven 2) to execute when none is specified for the project. |
resources
|
This element describes all of the resources associated with a project or unit tests. Each resource is described by a resource element, which is then described by additional elements (described below). These resources are used to complete the jar file or to run unit test. |
This element describes all of the sourceModifications associated with a
project. Each source modification is described by a
sourceModification
element, which is then described by
additional elements (described below). These modifications are used
to exclude or include various source depending on the environment
the build is running in.
Element | Description |
---|---|
className
|
If the class with this name can not be loaded, then the includes and excludes specified below will be applied to the contents of the sourceDirectory |
property
|
An optional property. |
directory
|
Describe the directory where the resource is stored. The path may be absolute, or relative to the project.xml file. |
includes
|
Files to include. |
excludes
|
Files to exclude. |
Element | Description |
---|---|
resources
|
Resources needed to run the unit tests. |
includes
|
Files to include. |
excludes
|
Files to exclude. |
This element describes all of the resources associated with a project or unit tests. Each resource is described by a resource element, which is then described by additional elements (described below). These resources are used to complete the jar file or to run unit test.
Element | Description |
---|---|
targetPath
|
Describe the resource target path. For example, if you want that
resource appear into a specific package
(org.apache.maven.messages ), you must specify this
element with this value : org/apache/maven/messages
|
filtering
|
Boolean. Describe if resources are filtered or not. |
directory
|
Describe the directory where the resource is stored. The path may be absolute, or relative to the project.xml file. |
includes
|
Resources to include. |
excludes
|
Resources to exclude. |
Element | Description |
---|---|
id
|
The name of the dependency.
Note: The use of the id element for
a dependency is deprecated. Please use |
groupId
|
The project group that produced the dependency, e.g.
geronimo .
|
artifactId
|
The unique id for an artifact produced by the project group, e.g.
germonimo-jms
|
version
|
The version of the dependency, e.g. 3.2.1
|
url
|
This url will be provided to the user if the jar file cannot be downloaded from the central repository. |
jar
|
Literal name of the artifact. Used to override the calculated artifact name. |
type
|
The type of dependency. This defaults to jar .
Known recognised dependency types are:
|
properties
|
Properties about the dependency. Various plugins allow you to
mark dependencies with properties. For example the
war plugin looks for a
war.bundle property, and if found will include the
dependency in WEB-INF/lib . For example syntax, check
the war plugin docs.
|