Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the announcement. Users are encouraged to migrate to the current version of Apache Maven.

Maven

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>

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

mailingList

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.

developer

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.

contributor

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.

license

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.
repo
may be downloaded from the Maven repository
manual
user must manually download and install the dependency.
comments Addendum information pertaining to this license.

version

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.

branch

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.

packageGroup

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.

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><delimiter><provider-parameters>

where <delimiter> can be either ':' (colon) or '|' (pipe).

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

organization

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.

build

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.

sourceModification

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.

unitTest

Element Description
resources Resources needed to run the unit tests.
includes Files to include.
excludes Files to exclude.

resource

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.

dependency

Element Description
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. 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:
  • jar
  • ejb
  • plugin
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.