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. 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 at http://maven.apache.org/xsd/maven-project-3.0.0.xsd. In addition, a sample project descriptor is presented in the Integration document. For those wondering, yes, Maven's build system is built by Maven (we believe in eating our own dog food :)
<project> <extend/> <pomVersion/> <id/> <name/> <groupId/> <currentVersion/> <organization> <name/> <url/> <logo/> </organization> <inceptionYear/> <package/> <logo/> <gumpRepositoryId/> <description/> <shortDescription/> <url/> <issueTrackingUrl/> <siteAddress/> <siteDirectory/> <distributionSite/> <distributionDirectory/> <repository> <connection/> <developerConnection/> <url/> </repository> <versions> <version> <id/> <name/> <tag/> </version> </versions> <branches> <branch> <tag/> </branch> </branches> <mailingLists> <mailingList> <name/> <subscribe/> <unsubscribe/> <archive/> </mailingList> </mailingLists> <developers> <developer> <name/> <id/> <email/> <organization/> <roles> <role/> </roles> <url/> <timezone/> </developer> </developers> <contributors> <contributor> <name/> <email/> <organization/> <roles> <role/> </roles> <url/> <timezone/> </contributor> </contributors> <licenses> <license> <name/> <url/> <distribution/> </license> </licenses> <dependencies> <dependency> <id/> <groupId/> <artifactId/> <version/> <jar/> <type/> <url/> <properties> </properties> </dependency> </dependencies> <build> <nagEmailAddress/> <sourceDirectory/> <sourceModifications> <sourceModification> <className/> <includes> <include/> </includes> <excludes> <exclude/> </excludes> </sourceModification> </sourceModifications> <unitTestSourceDirectory/> <integrationUnitTestSourceDirectory/> <aspectSourceDirectory/> <unitTest> <includes> <include/> </includes> <excludes> <exclude/> </excludes> <resources> <resource> <directory/> <targetPath/> <includes> <include/> </includes> <excludes> <exclude/> </excludes> </resource> </resources> </unitTest> <resources> <resource> <directory/> <targetPath/> <includes> <include/> </includes> <excludes> <exclude/> </excludes> </resource> </resources> </build> <reports> <report> </reports> <properties/> </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.
|
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. |
name | The full name of the project. This value is used when generating JavaDoc titles. |
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. |
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. |
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.
|
gumpRepositoryId | Optional. This is the Id of the Gump repository that this project is part of (assuming it participates in the Gump integration effort). |
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 project's web site. |
shortDescription | A short description of the project. The short description should be limited to a single line. |
url | The URL to the project's homepage. |
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. |
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. |
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.
|
branches |
Optional. Contains information on branches 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. |
licenses | 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. |
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. |
reports | Describes the reports that should be included as part of the Maven-generated site. |
properties | Project properties that will be used by various plugins |
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 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 | Optional. Just like connection, but for developers, i.e. this scm connection will not be read only. |
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 each of the branches of the
project. Each branch is described by a tag
element
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. |
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. |
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.
|
url | The URL for the homepage of the developer |
timezone | The timezone the developer is in. This is a number in the range -14 to 14. |
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. |
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.
|
url | The URL for the homepage of the contributor |
timezone | The timezone the contributor is in. This is a number in the range -14 to 14. |
This element describes all of the licenses for this project. Each license is described by a
license
element, which is then describe 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.
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.
|
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.
Maven can automatically download these dependencies from a remote repository.
The filename that Maven downloads from the repository is
artifactId-version.jar
where artifactId
corresponds to the artifactId
element and version
corresponds to the
version
element.
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
${maven.repo.remote}
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. jboss .
|
artifactId |
The unique id for an artifact produced by the project group, e.g.
jboss-boot
|
version | The version of the dependency., e.g. 3.2.1 |
jar |
The name of jar file if it doesn't respect
<artifactId>-<version>.jar pattern. |
type |
The type of dependency. This defaults to jar .
Other known and recognised dependency types are:
|
url |
The url of the dependency's homepage.
This url will be provided to the user if the jar file cannot be downloaded from the central repository. |
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.
|
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 |
---|---|
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. |
sourceModifications | This element specifies how source code will be excluded or included depending on the presence of a given class. e.g. |
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. |
integrationUnitTestSourceDirectory | This element is deprecated and should no longer be used. Initially it was used by the first Cactus plugin. Now the location of the Cactus test sources is defined through a plugin property. See the Cactus plugin properties page. |
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. |
unitTest | This element specifies unit tests associated with the project. |
resources | Describe the resources associated with the project |
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 |
includes | Describe the files to be included if the class was not found |
excludes | Describe the files to be excluded if the class was not found |
Note: not all plugins support the sourceModifications element.
An example below always excludes the classes beginning with EJS
and _
.
Element | Description |
---|---|
includes | Describe the includes unit tests |
excludes | Describe the excludes unit tests |
resources | Describe the resources associated with unit tests |
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 |
---|---|
resource | Each resource must be defined in a resource element. |
Here's an example resources
block
Element | Description |
---|---|
directory | Describe the directory where the resource is stored. The path may be absolute, or relative to the project.xml file. |
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
|
includes | Describe the includes files to the project |
excludes | Describe the excludes files to the project |
filtering | Boolean. Describe if resources are filtered or not. |
Element | Description |
---|---|
include | This element specifies an Ant pattern of files to include in a list. |
Element | Description |
---|---|
exclude | This element specifies an Ant pattern of files to exclude from a list. |
This element includes the specification of reports to be
included in a Maven-generated site. These reports will be run
when a user executes maven site
. All of the
reports will be included in the navigation bar for browsing in
the order they are specified.
Element | Description |
---|---|
report |
The name of the report that should be run when the site is
generated. There is an established naming convention that
is to be used when specifying reports. If you want the
report that is generated by a plugin called
xyz , then you would specify the following for
the value of this element: maven-xyz-plugin .
|