Pete Kazmier dIon Gillard 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. 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. 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.

ElementDescription
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. ${basedir}/../project.xml]]>
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 maven.repo.central and maven.repo.central.directory

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

ElementDescription
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.
ElementDescription
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
Remember that CVS will expect an environment variable called 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 Note the use of the vertical bar as delimiter as the repository has a colon (:) 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
All of this information can be had from either the StarTeam Universal Client (Tools->Server Administration->Server Properties) or from the administrator.

The delimiter is determined by the character after "scm". eg. scm|cvs|pserver|user@host|/cvs/root|module-name is equivalent to that listed above. This can be useful for Windows users who have : in their cvsroot parameter (eg. D:\cvsroot)

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

ElementDescription
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

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

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

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

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

ElementDescription
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.
repo
may be downloaded from the Maven repository
manual
user must manually download and install the dependency.

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

repo
is the remote repository URL specified by ${maven.repo.remote}
groupId
is taken from the dependency element
type
is taken from the dependency element
artifactId
is taken from the dependency element
version
is taken from the dependency element

ElementDescription
id

The name of the dependency.

Note: The use of the id element for a dependency is deprecated. Please use groupId and artifactId together instead.

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: ejb and plugin.

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.

There are two special properties that are built into the maven core for specifying the location of the dependency:

  • project.path specifies a path relative to the project.xml file to locate the dependency. If it cannot find the file specified by this property then it will attempt to use the following value.
  • local.path specifies a path relative to the local file system to locate the dependency. project.path has a higher priority than this one, so if the project.path property exists (and the file it refers to exists as well) it will override the value here. If the value referred by this property does not exist in the file system, then it will use the standard maven resolution methods with no log messages.

Please note that theoretically you can specify the values above by using the maven.jar.<id> property in project.properties this will allow you to retain the <groupId> and <artifactId> tags in your dependency (which is the way it should be as a the <id> tag is deprecated.

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:

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

sourceModification elements

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

fakeClass **/EJS*.java **/_*.java ]]>
ElementDescription
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.

ElementDescription
resource Each resource must be defined in a resource element.

Here's an example resources block

${basedir}/src/resources/misc *.xsd ${basedir}/src/resources/logging log4j.properties ]]>
ElementDescription
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.
ElementDescription
include This element specifies an Ant pattern of files to include in a list.
ElementDescription
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.

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