Maven Project Descriptors

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 :)

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
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.

organization

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.

repository

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

versions

This element describes each of the previous versions of the project. Each version is described by a version element

version

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.

mailingLists

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.

mailingList

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.

developers

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.

developer

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.

contributors

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.

contributor

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.

dependencies

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.

dependency

Element Description
id The name of the dependency.
version The version of the dependency.
url The url of the dependency's homepage.

build

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.

jarResources

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.

unitTestPatterns

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.

integrationUnitTestPatterns

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.

jars

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.