From c5d3edfeb9401c3ad8b0b88105fbf925ae132ab8 Mon Sep 17 00:00:00 2001 From: Brett Leslie Porter Date: Fri, 10 Mar 2006 02:41:32 +0000 Subject: [PATCH] [MNG-1479, MNG-1177, MNG-1658] update the project descriptor descriptions git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@384682 13f79535-47bb-0310-9956-ffa450edef68 --- maven-model/maven.mdo | 863 ++++++++++++++++++------------------------ 1 file changed, 362 insertions(+), 501 deletions(-) diff --git a/maven-model/maven.mdo b/maven-model/maven.mdo index 8ab7298a9e..c8c404e78d 100644 --- a/maven-model/maven.mdo +++ b/maven-model/maven.mdo @@ -45,11 +45,8 @@ Model ModelBase <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. + The <project> element is the root of the descriptor. + The following table lists all of the possible child elements. ]]> 3.0.0+ @@ -60,16 +57,19 @@ 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>
+ current project.xml file. For example, + <extend>${basedir}/../project.xml</extend>. ]]> String parent 4.0.0 - + Parent @@ -87,33 +87,17 @@ 3.0.0 true String - - - - id - 3.0.0 - true - jars and - distribution files. - ]]> - String + + 3.]]> groupId 3.0.0+ true user guide. + A universally unique identifier for a project. It is normal to + use a fully-qualified package name to distinguish it from other projects with a similar name + (eg. org.apache.maven). ]]> String @@ -122,10 +106,19 @@ 3.0.0+ true groupId - when naming jars and - distribution files. + The identifier for this artifact that is unique within the group given by the group ID. + An artifact is something that is either produced or used by a project. Examples of artifacts produced by + Maven for a project include: JARs, source and binary distributions, and WARs. + ]]> + String + + + id + 3.0.0 + true + Deprecated. When used, this sets both the groupId and artifactId elements + if they were previously empty. ]]> String @@ -133,19 +126,13 @@ packaging 4.0.0 -
  • jar
    • -
  • war
    • -
  • ear
    • -
  • pom
    • - -

    - However, plugins can create their own packaging, and + The type of artifact this project produces, for example jar + war + ear + pom. + Plugins can create their own packaging, and therefore their own packaging types, - so this list can not contain all possible types. -

    + so this list does not contain all possible types. ]]>     String jar @@ -155,18 +142,14 @@ 3.0.0+ true JavaDoc - titles. + The full name of the project. ]]> String currentVersion jars and - distribution files. + The current version of the artifact produced by this project. ]]> 3.0.0 true @@ -194,14 +177,11 @@ description 3.0.0+ 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. + A detailed description of the project, used by Maven whenever it needs to describe the project, + such as on the web site. While this element can be specified as CDATA to enable + the use of HTML tags within the description, it is discouraged to allow plain text representation. + If you need to modify the index page of the generated web site, you are able to specify your own instead + of adjusting this text. ]]> String @@ -217,7 +197,7 @@ logo 3.0.0 /images/project-logo.png) or an absolute URL (e.g., http://my.corp/project-logo.png). This is used @@ -239,14 +219,14 @@ issueTrackingUrl 3.0.0 String issueManagement 4.0.0 - + IssueManagement @@ -254,7 +234,7 @@ ciManagement 4.0.0 - + CiManagement @@ -264,9 +244,8 @@ 3.0.0+ true JavaDoc copyright notices. + The year of the project's inception, specified with 4 digits. + This value is used when generating copyright notices as well as being informational. ]]> String @@ -274,9 +253,7 @@ gumpRepositoryId 3.0.0 String @@ -284,9 +261,8 @@ siteAddress 3.0.0 deployed. + The hostname of the web server that hosts the project's web site. This is used when the web site is + deployed. ]]> String @@ -294,9 +270,8 @@ siteDirectory 3.0.0 deployed. + The directory on the web server where the public web site + for this project resides. This is used when the web site is deployed. ]]> String @@ -304,38 +279,26 @@ distributionSite 3.0.0 deployed. -

    - If this isn't defined, the central repository is used instead as - determined by maven.repo.central and - maven.repo.central.directory -

    + The 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. ]]>     String - This naming is inconsistent and distribution should occur from a repository structure. distributionDirectory 3.0.0 deployed. + The directory on the web server where the final distributions will be published. This is used when the + distributions are deployed. ]]> String - This naming is inconsistent and distribution should occur from a repository structure. mailingLists 3.0.0+ front - page of the site's web site. + Contains information about a project's mailing lists. ]]> MailingList @@ -346,9 +309,7 @@ developers 3.0.0+ Project Team - page of the project's web site. + Describes the committers of a project. ]]> Developer @@ -359,9 +320,7 @@ contributors 3.0.0+ Project Team page of - the project's web site. + Describes the contributors to a project that are not yet committers. ]]> Contributor @@ -374,10 +333,11 @@ license element, which - is then described by additional elements (described below). The - auto-generated site documentation references this information. + is then described by additional elements. Projects should only list the license(s) that applies to the project and not the licenses that apply to dependencies. + If multiple licenses are listed, it is assumed that the user can select any of them, not that they + must accept all. ]]> License @@ -388,10 +348,7 @@ versions 3.0.0 maven:dist - target. + Contains information on previous versions of the project. ]]> Version @@ -402,10 +359,7 @@ branches 3.0.0 maven:dist - target. + Contains information on SCM branches of the project. ]]> Branch @@ -439,7 +393,8 @@ scm 4.0.0 - + + Scm @@ -447,12 +402,11 @@ repository 3.0.0 - + + Repository - This element needs to be renamed as it conflicts with the existing notion of repositories in - Maven. organization @@ -471,7 +425,7 @@ properties 3.0.0 <name>value</name>. ]]> Properties @@ -485,7 +439,7 @@ String JavaDoc. + when generating JavaDoc. ]]> @@ -501,7 +455,7 @@ profiles 4.0.0 Profile @@ -513,7 +467,6 @@ 3.0.0 modules 4.0.0 - The modules to build in addition to the current project + + The modules (sometimes called subprojects) to build as a part of this project. + Each module listed is a relative path to the directory containing the module. + String * @@ -573,7 +529,8 @@ repositories 4.0.0 - + Repository * @@ -582,81 +539,35 @@ pluginRepositories 4.0.0 - + + Repository * - This may be removed or relocated in the near future. It is undecided whether plugins really need a - remote repository set of their own. dependencies 3.0.0+ 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). -

    -

    + project. 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
    -
    + project during the build process. They are automatically downloaded from the + repositories defined in this project. + See the + dependency mechanism for more information. ]]>     Dependency * - These should ultimately only be compile time dependencies when transitive dependencies come into - play.     reports 4.0.0 Deprecated. Now ignored by Maven. ]]> DOM @@ -664,11 +575,9 @@ reporting 4.0.0 maven site    . All of the - reports will be included in the navigation bar for browsing in - the order they are specified. + This element includes the specification of report plugins to use to generate the reports on the + Maven-generated site. These reports will be run when a user executes mvn site. All of the + reports will be included in the navigation bar for browsing. ]]>     Reporting @@ -679,13 +588,11 @@ 4.0.0 false DependencyManagement @@ -694,7 +601,8 @@ distributionManagement 4.0.0 - + DistributionManagement @@ -703,7 +611,8 @@ properties 4.0.0 <name>value</name>. ]]> Properties @@ -713,14 +622,11 @@     - Branch 3.0.0 maven:dist target. + Contains information on the SCM branches of the project. ]]> @@ -744,10 +650,7 @@ plugins 4.0.0 - The plugins specified here are not validated until they - are referenced in a POM within the group. This allows the - specification of a "standard" version for a particular - plugin. + The list of plugins to use. Plugin @@ -800,7 +703,7 @@ @@ -827,11 +730,8 @@ resources 3.0.0+ below). These resources are used to complete - the jar file or to run unit test. + This element describes all of the classpath resources such as properties files associated with a + project. These resources are often included in the final package. ]]> Resource @@ -842,11 +742,8 @@ testResources 4.0.0 below). These resources are used to complete - the jar file or to run unit test. + This element describes all of the classpath resources such as properties files associated with a + project's unit tests. ]]> Resource @@ -857,7 +754,7 @@ directory 4.0.0 String @@ -866,7 +763,7 @@ 4.0.0 ${artifactId}-${version}. ]]> String @@ -895,9 +792,7 @@ 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. + continuous integration. ]]> String @@ -934,7 +829,6 @@ 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. ]]> String @@ -947,7 +841,6 @@ 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. ]]> String @@ -959,9 +852,7 @@ 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). + built if Aspects have been enabled. The path given is relative to the project descriptor. ]]> String @@ -971,7 +862,7 @@ 3.0.0 String @@ -981,9 +872,7 @@ true sourceModification element, which is then described by - additional elements (described below). These modifications are used + with a project. These modifications are used to exclude or include various source depending on the environment the build is running in. ]]> @@ -1038,13 +927,15 @@ system 4.0.0 - + + continuum.]]> String url 4.0.0 - + + String @@ -1080,37 +971,37 @@ 4.0.0 true boolean - Send notification on error. + Whether to send notifications on error. sendOnFailure 4.0.0 true boolean - Send notification on failure. + Whether to send notifications on failure. sendOnSuccess 4.0.0 true boolean - Send notification on success. + Whether to send notifications on success. sendOnWarning 4.0.0 true boolean - Send notification on warning. + Whether to send notifications on warning. address 4.0.0 String - - Where to send the notification to - eg email address. DEPRECATED. - + Deprecated. Where to send the notification to - eg email address. + ]]> configuration @@ -1171,7 +1062,7 @@ role element, the body of which is a - role name. + role name. This can also be used to describe the contribution. ]]> String @@ -1209,12 +1100,8 @@ 3.0.0 true The name of the dependency.

    -

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

    ]]>     String     @@ -1224,7 +1111,7 @@ true geronimo. + org.apache.maven. ]]> String @@ -1234,7 +1121,7 @@ true germonimo-jms + maven-artifact. ]]> String @@ -1242,7 +1129,8 @@ version 3.0.0+ 3.2.1 + The version of the dependency, e.g. 3.2.1. In Maven 2, this can also be + specified as a range of versions. ]]> String @@ -1254,27 +1142,39 @@ from the central repository. ]]> String - The URL should really be gleaned from a shared database of dependency information. jar 3.0.0 String type - 3.0.0+ + 3.0.0 jar. - Known recognised dependency types are: -
      -
    • jar
      • -
    • ejb
      • -
    • plugin
      • -
    + The type of dependency. This defaults to jar. While it usually represents the extension on + the filename of the dependency, that is not always the case. + Some examples are jar, war, and plugin. + A dependency of type plugin is loaded as a Maven plugin and not added to the project + build classpath. + ]]>     + String + jar +     + + type + 4.0.0 + jar. While it usually represents the extension on + the filename of the dependency, that is not always the case. A type can be mapped to a different + extension and a classifier. + The type often correspongs to the packaging used, though this is also not always the case. + Some examples are jar, war, ejb-client and test-jar. + New types can be defined by plugins that set + extensions to true, so this is not a complete list. ]]> String jar @@ -1282,10 +1182,11 @@ classifier 4.0.0 - + + were built differently, and is appended to the filename after the version. For example, + jdk14 and jdk15. + ]]> String false @@ -1294,11 +1195,9 @@ 3.0.0 mark dependencies with properties. For example the - war plugin looks for a + 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. + dependency in WEB-INF/lib. ]]> Properties @@ -1310,11 +1209,12 @@ scope 4.0.0 Dependency Mechanism.]]> + The scope of the dependency - compile, runtime, test, + system, and provided. Used to + calculate the various classpaths used for compilation, testing, and so on. It also assists in determining + which artifacts to include in a distribution of this project. For more information, see + the + dependency mechanism.]]> String + 4.0.0 @@ -2284,18 +2106,19 @@ RepositoryBase 4.0.0 - Repository contains the information needed for deploying to the remote repoistory + Repository contains the information needed for deploying to the remote repoistory. uniqueVersion - Whether to assign snapshots a unique version comprised of the timestamp and build number, or to use the same version each time + Whether to assign snapshots a unique version comprised of the timestamp and build number, or to + use the same version each time boolean true 4.0.0 - + 4.0.0 @@ -2317,23 +2140,37 @@ enabled 4.0.0 - Whether to use this repository for downloading this type of artifact + Whether to use this repository for downloading this type of artifact. boolean true updatePolicy 4.0.0 - - The frequency for downloading updates - can be "always", "daily" (default), "interval:XXX" (in minutes) or - "never" (only if it doesn't exist locally). - + always, + daily + (default), + interval:XXX + (in minutes) or + never + (only if it doesn't exist locally). + ]]> String checksumPolicy 4.0.0 - What to do when verification of an artifact checksum fails. Valid values are "ignore", "fail" or "warn" + ignore + , + fail + or + warn + (the default). + ]]> String     @@ -2344,15 +2181,15 @@ Site 4.0.0 id 4.0.0 settings.xml file, for example. ]]> String @@ -2360,7 +2197,7 @@ name 4.0.0 String @@ -2368,7 +2205,7 @@ url 4.0.0 protocol://hostname/path. ]]> String @@ -2383,7 +2220,7 @@ inherited 4.0.0 - + String @@ -2417,6 +2254,7 @@ groupId + The group ID of the plugin in the repository. 4.0.0 String true @@ -2424,6 +2262,7 @@ artifactId + The artifact ID of the plugin in the repository. 4.0.0 String true @@ -2432,7 +2271,7 @@ version 4.0.0 true - + String @@ -2440,14 +2279,15 @@ 4.0.0 boolean Whether to load Maven extensions (such as packaging and type handlers) from this - plugin + plugin. For performance reasons, this should only be enabled when necessary. false executions 4.0.0 - Multiple specifications of a set of goals, each having (possibly) different - configuration + Multiple specifications of a set of goals to execute during the build lifecycle, each having + (possibly) different + configuration. PluginExecution * @@ -2455,7 +2295,8 @@ dependencies - Additional dependencies that this project needs to introduce to the plugin + Additional dependencies that this project needs to introduce to the plugin's + classloader. 4.0.0 Dependency @@ -2466,7 +2307,7 @@ goals 4.0.0 Deprecated. Unused by Maven. ]]> DOM @@ -2530,15 +2371,20 @@ true String default + The identifier of this execution for labelling the goals during the build, and for matching + exections to merge during inheritance. phase 4.0.0 String + The build lifecycle phase to bind the goals in this execution to. If omitted, the goals will + be bound to the default specified in their metadata. goals 4.0.0 + The goals to execute with the given configuration. String * @@ -2565,7 +2411,7 @@ dependencies 4.0.0 - The dependencies specified here are not validated until they + The dependencies specified here are not used until they are referenced in a POM within the group. This allows the specification of a "standard" version for a particular dependency. @@ -2588,25 +2434,31 @@ Reporting 4.0.0 - Section for management of reports and configuration + Section for management of reports and their configuration. excludeDefaults 4.0.0 boolean - If true, then the default reports are not included in the site generation + If true, then the default reports are not included in the site generation. This includes the + reports in the "Project Info" menu. false outputDirectory 4.0.0 String - Where to store all of the generated reports + ${project.build.directory}/site + . + ]]> + plugins 4.0.0 - The report plugins) to use and their configuration + The reporting plugins to use and their configuration. ReportPlugin * @@ -2650,8 +2502,7 @@ ModelBase 4.0.0 @@ -2659,8 +2510,8 @@ true 4.0.0 String - The ID of this build profile, for activation - purposes. + The identifier of this build profile. This used both for command line activation, and identifies + identical profiles to merge with during inheritance. activation @@ -2712,28 +2563,29 @@ 4.0.0 activeByDefault 4.0.0 boolean - Flag specifying whether this profile is active as a default. + Flag specifying whether this profile is active by default. jdk 4.0.0 String 1.4 + only activates on JDKs versioned 1.4, while !1.4 matches any JDK that is not version 1.4. ]]> os 4.0.0 ActivationOS @@ -2743,7 +2595,7 @@ property 4.0.0 ActivationProperty @@ -2775,13 +2627,13 @@ 4.0.0 String true - The name of the property to be used to activate a profile + The name of the property to be used to activate a profile. value 4.0.0 String - The value of the property to be used to activate a profile + The value of the property required to activate a profile. @@ -2797,25 +2649,27 @@ name 4.0.0 String - The name of the OS to be used to activate a profile + ${os.name} Java property, such as Windows XP.]]> family 4.0.0 String - The general family of the OS to be used to activate a profile (e.g. 'windows') + + windows or unix.]]> arch 4.0.0 String - The architecture of the OS to be used to activate a profile + The architecture of the operating system to be used to activate the profile. version 4.0.0 String - The version of the OS to be used to activate a profile + The version of the operating system to be used to activate the profile.     @@ -2823,22 +2677,22 @@ ActivationFile 4.0.0 missing 4.0.0 String - The name of the file that should be missing to activate a profile + The name of the file that must be missing to activate the profile. exists 4.0.0 String - The name of the file that should exist to activate a profile + The name of the file that must exist to activate the profile. @@ -2853,34 +2707,39 @@ String true org.apache.maven.plugins + The group ID of the reporting plugin in the repository. artifactId 4.0.0 String true + The artifact ID of the reporting plugin in the repository. version 4.0.0 - + String inherited 4.0.0 String + Whether the configuration in this plugin should be made available to projects that + inherit from this one. configuration 4.0.0 DOM + The configuration of the reporting plugin. reportSets 4.0.0 - Multiple specifications of a set of reports, each having (possibly) different - configuration + execution in the build.]]> ReportSet * @@ -2956,20 +2815,22 @@ configuration 4.0.0 + Configuration of the report to be used when generating this set. DOM inherited 4.0.0 String + + reports 4.0.0 true String @@ -2999,14 +2860,14 @@ Prerequisites 4.0.0 - Describes the prerequisites a project can have + Describes the prerequisites a project can have. maven 4.0.0 String 2.0 - The minimum version of Maven required + The minimum version of Maven required to build the project, or to use this plugin. false @@ -3020,19 +2881,19 @@ groupId 4.0.0 - The group the artifact has moved to + The group ID the artifact has moved to. String artifactId 4.0.0 - The new artifact ID of the artifact + The new artifact ID of the artifact. String version 4.0.0 - The new version of the artifact + The new version of the artifact. String @@ -3046,26 +2907,26 @@ Extension 4.0.0 - Describes a build extension to utilise + Describes a build extension to utilise. groupId 4.0.0 - The group of the extension's artifact. + The group ID of the extension's artifact. true String artifactId 4.0.0 - The artifact ID of the extension + The artifact ID of the extension. true String version 4.0.0 - The version of the extension + The version of the extension. String