| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ----- |
| Introduction |
| ----- |
| Hervé Boutemy |
| ----- |
| 2013-03-19 |
| ----- |
| |
| Maven Model Builder |
| |
| The effective model builder, with profile activation, inheritance, interpolation, ... |
| |
| The main component is <<<ModelBuilder>>> |
| ({{{./apidocs/org/apache/maven/model/building/ModelBuilder.html}javadoc}}, |
| {{{./xref/org/apache/maven/model/building/ModelBuilder.html}source}}), |
| with its <<<DefaultModelBuilder>>> implementation |
| ({{{./apidocs/org/apache/maven/model/building/DefaultModelBuilder.html}javadoc}}, |
| {{{./xref/org/apache/maven/model/building/DefaultModelBuilder.html}source}}) |
| that manages the steps sequence. |
| |
| The sequence is divided into 2 phases: |
| |
| * phase 1 |
| |
| ** profile activation: see {{{./apidocs/org/apache/maven/model/profile/activation/package-summary.html}available activators}}. |
| Notice that model interpolation hasn't happened yet, then interpolation for file-based activation is limited to |
| <<<$\{basedir}>>> (since Maven 3), System properties and request properties |
| |
| ** file model validation: <<<ModelValidator>>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), |
| with its <<<DefaultModelValidator>>> implementation |
| ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) |
| |
| [] |
| |
| * phase 2, with optional plugin processing |
| |
| ** Build up a raw model by re-reading the file and enrich it based on information available in the reactor. Some features: |
| |
| *** Resolve version of versionless parents based on realtivePath (including ci-friendly versions) |
| |
| *** Resolve version of versionless dependencies that are part of the reactor |
| |
| [] |
| |
| ** raw model validation: <<<ModelValidator>>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), |
| with its <<<DefaultModelValidator>>> implementation |
| ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) |
| |
| ** model normalization - merge duplicates: <<<ModelNormalizer>>> ({{{./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html}javadoc}}), |
| with its <<<DefaultModelNormalizer>>> implementation |
| ({{{./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html}source}}) |
| |
| ** profile injection: <<<ProfileInjector>>> ({{{./apidocs/org/apache/maven/model/profile/ProfileInjector.html}javadoc}}), |
| with its <<<DefaultProfileInjector>>> implementation |
| ({{{./xref/org/apache/maven/model/profile/DefaultProfileInjector.html}source}}) |
| |
| ** parent resolution until {{{./super-pom.html}super-pom}} |
| |
| ** inheritance assembly (see {{{./index.html#Inheritance_Assembly}below}}) |
| |
| ** model interpolation (see {{{./index.html#Model_Interpolation}below}}) |
| |
| ** url normalization: <<<UrlNormalizer>>> ({{{./apidocs/org/apache/maven/model/path/UrlNormalizer.html}javadoc}}), |
| with its <<<DefaultUrlNormalizer>>> implementation |
| ({{{./xref/org/apache/maven/model/path/DefaultUrlNormalizer.html}source}}) |
| |
| ** model path translation: <<<ModelPathTranslator>>> ({{{./apidocs/org/apache/maven/model/path/ModelPathTranslator.html}javadoc}}), |
| with its <<<DefaultModelPathTranslator>>> implementation |
| ({{{./xref/org/apache/maven/model/path/DefaultModelPathTranslator.html}source}}) |
| |
| ** plugin management injection: <<<PluginManagementInjector>>> ({{{./apidocs/org/apache/maven/model/management/PluginManagementInjector.html}javadoc}}), |
| with its <<<DefaultPluginManagementInjector>>> implementation |
| ({{{./xref/org/apache/maven/model/management/DefaultPluginManagementInjector.html}source}}) |
| |
| ** <(optional)> lifecycle bindings injection: <<<LifecycleBindingsInjector>>> ({{{./apidocs/org/apache/maven/model/plugin/LifecycleBindingsInjector.html}javadoc}}), |
| with its <<<DefaultLifecycleBindingsInjector>>> implementation in maven-core |
| ({{{./maven-core/xref/org/apache/maven/model/plugin/DefaultLifecycleBindingsInjector.html}source}}) |
| |
| ** dependency management import (for dependencies of type <<<pom>>> in the <<<\<dependencyManagement\>>>> section) |
| |
| ** dependency management injection: <<<DependencyManagementInjector>>> ({{{./apidocs/org/apache/maven/model/management/DependencyManagementInjector.html}javadoc}}), |
| with its <<<DefaultDependencyManagementInjector>>> implementation |
| ({{{./xref/org/apache/maven/model/management/DefaultDependencyManagementInjector.html}source}}) |
| |
| ** model normalization - inject default values: <<<ModelNormalizer>>> ({{{./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html}javadoc}}), |
| with its <<<DefaultModelNormalizer>>> implementation |
| ({{{./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html}source}}) |
| |
| ** <(optional)> reports configuration: <<<ReportConfigurationExpander>>> ({{{./apidocs/org/apache/maven/model/plugin/ReportConfigurationExpander.html}javadoc}}), |
| with its <<<DefaultReportConfigurationExpander>>> implementation |
| ({{{./xref/org/apache/maven/model/plugin/DefaultReportConfigurationExpander.html}source}}) |
| |
| ** <(optional)> reports conversion to decoupled site plugin: <<<ReportingConverter>>> ({{{./apidocs/org/apache/maven/model/plugin/ReportingConverter.html}javadoc}}), |
| with its <<<DefaultReportingConverter>>> implementation |
| ({{{./xref/org/apache/maven/model/plugin/DefaultReportingConverter.html}source}}) |
| |
| ** <(optional)> plugins configuration: <<<PluginConfigurationExpander>>> ({{{./apidocs/org/apache/maven/model/plugin/PluginConfigurationExpander.html}javadoc}}), |
| with its <<<DefaultPluginConfigurationExpander>>> implementation |
| ({{{./xref/org/apache/maven/model/plugin/DefaultPluginConfigurationExpander.html}source}}) |
| |
| ** effective model validation: <<<ModelValidator>>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), |
| with its <<<DefaultModelValidator>>> implementation |
| ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) |
| |
| [] |
| |
| [] |
| |
| |
| * Inheritance Assembly |
| |
| Inheritance Assembly consists in filling current model empty fields with values taken from parent model. |
| It is done in <<<InheritanceAssembler>>> ({{{./apidocs/org/apache/maven/model/inheritance/InheritanceAssembler.html}javadoc}}), |
| with its <<<DefaultInheritanceAssembler>>> implementation |
| ({{{./xref/org/apache/maven/model/inheritance/DefaultInheritanceAssembler.html}source}}). |
| |
| By default, every model field is inherited as-is from parent, with a few exceptions that are intentionally not inherited: |
| <<<modelVersion>>>, <<<artifactId>>>, <<<profiles>>> (injected in phase 1) and <<<prerequisites>>>. |
| |
| Notice that the 5 URLs from the model (<<<project.url>>>, <<<project.scm.connection>>>, <<<project.scm.developerConnection>>>, |
| <<<project.scm.url>>> and <<<project.distributionManagement.site.url>>>) have a special inheritance handling: |
| |
| ** if not configured in current model, the inherited value is the parent's one with current artifact id appended, |
| |
| ** since Maven 3.5.0, if <<<project.directory>>> POM property value is defined, it is used instead of artifact id: |
| this permits default inheritance calculations when module directory name is not equal to artifact id. Notice that this |
| property is not inherited from a POM to its child: childs POM will use child artifact id if property is not |
| set. |
| |
| ** since Maven 3.6.1, inheritance can avoid appending any path to parent value by setting model attribute value to |
| <<<false>>> for each url: |
| <<<project/@child.project.url.inherit.append.path>>>, |
| <<<project/distributionManagement/site/@child.site.url.inherit.append.path>>>, |
| <<<project/scm/@child.scm.connection.inherit.append.path>>>, |
| <<<project/scm/@child.scm.developerConnection.inherit.append.path>>> and |
| <<<project/scm/@child.scm.url.inherit.append.path>>>. |
| |
| [] |
| |
| * Model Interpolation |
| |
| Model Interpolation consists in replacing <<<$\{...\}>>> with calculated value. It is done in <<<StringSearchModelInterpolator>>> |
| ({{{./apidocs/org/apache/maven/model/interpolation/StringSearchModelInterpolator.html}javadoc}}, |
| {{{./xref/org/apache/maven/model/interpolation/StringSearchModelInterpolator.html}source}}). |
| |
| Notice that model interpolation happens <after> profile activation, then profile activation doesn't benefit from every values: |
| interpolation for file-based activation is limited to <<<$\{basedir}>>> (which was introduced in Maven 3 and is not deprecated |
| in this context), System properties and request properties. |
| |
| Values are evaluated in sequence from different syntaxes: |
| |
| *----+------+------+ |
| || value || evaluation result || common examples || |
| *----+------+------+ |
| | <<<project.*>>>\ |
| <<<pom.*>>> (<deprecated>)\ |
| <<<*>>> (<deprecated>) | POM content (see {{{../maven-model/maven.html}POM reference}}) | <<<$\{project.version\}>>>\ |
| | | <<<$\{project.build.finalName\}>>>\ |
| | | <<<$\{project.artifactId\}>>>\ |
| | | <<<$\{project.build.directory\}>>> | |
| *----+------+------+ |
| | <<<project.basedir>>>\ |
| <<<pom.basedir>>> (<deprecated>)\ |
| <<<basedir>>> (<deprecated>) | the directory containing the <<<pom.xml>>> file | <<<$\{project.basedir\}>>> | |
| *----+------+------+ |
| | <<<project.baseUri>>>\ |
| <<<pom.baseUri>>> (<deprecated>) | the directory containing the <<<pom.xml>>> file as URI | <<<$\{project.baseUri\}>>> | |
| *----+------+------+ |
| | <<<build.timestamp>>>\ |
| <<<maven.build.timestamp>>> | the UTC timestamp of build start, in <<<yyyy-MM-dd'T'HH:mm:ss'Z'>>> default format, which can be overridden with <<<maven.build.timestamp.format>>> POM property | <<<$\{maven.build.timestamp\}>>> | |
| *----+------+------+ |
| | <<<*>>> | user properties, set from CLI with <<<-Dproperty=value>>> | <<<$\{skipTests\}>>> | |
| *----+------+------+ |
| | <<<*>>> | model properties, such as project properties set in the pom | <<<$\{any.key\}>>> | |
| *----+------+------+ |
| | <<<maven.home>>> | The path to the current Maven home. | <<<$\{maven.home\}>>> | |
| *----+------+------+ |
| | <<<maven.version>>> | The version number of the current Maven execution <(since 3.0.4)>. For example, "<<<3.0.5>>>". | <<<$\{maven.version\}>>> | |
| *----+------+------+ |
| | <<<maven.build.version>>> | The full build version of the current Maven execution <(since 3.0.4)>. For example, "<<<Apache Maven 3.2.2 (r01de14724cdef164cd33c7c8c2fe155faf9602da; 2013-02-19T14:51:28+01:00)>>>". | <<<$\{maven.build.version\}>>> | |
| *----+------+------+ |
| | <<<maven.repo.local>>> | The repository on the local machine Maven shall use to store installed and downloaded artifacts (POMs, JARs, etc). | <<<$\{user.home\}/.m2/repository>>> | |
| *----+------+------+ |
| | <<<*>>> | Java system properties (see {{{http://download.oracle.com/javase/6/docs/api/java/lang/System.html#getProperties()}JDK reference}}) | <<<$\{user.home\}>>>\ |
| | | <<<$\{java.home\}>>> | |
| *----+------+------+ |
| | <<<env.*>>>\ |
| <<<*>>> | environment variables | <<<$\{env.PATH\}>>> | |
| *----+------+------+ |
| | <<<settings.*>>> | Local user settings (see {{{../maven-settings/settings.html}settings reference}}) | <<<$\{settings.localRepository\}>>> | |
| *----+------+------+ |
| | <<<changelist>>> \ |
| <<<revision>>> \ |
| <<<sha1>>> | CI friendly placeholders for the project version (see {{{/maven-ci-friendly.html}Maven CI Friendly Versions}}) | <<<1.0.0-$\{changelist\}-SNAPSHOT>>> | |
| *----+------+------+ |
| |
| |
| ** Notice |
| |
| * after model interpolation, <<<$\{...\}>>> content can remain in the model that will be evaluated later |
| when setting plugin parameters. This happens in particular with <<<settings.*>>> values for |
| {{{../maven-settings/settings.html}Settings Model}}, |
| |
| * encoding configuration have been defined as POM properties looking like POM content but not added to POM model to maintain |
| compatibility with previous Maven versions: |
| |
| * <<<$\{project.build.sourceEncoding\}>>> for |
| {{{https://cwiki.apache.org/confluence/display/MAVEN/POM+Element+for+Source+File+Encoding}source files encoding}} |
| (defaults to platform encoding) |
| |
| * <<<$\{project.reporting.outputEncoding\}>>> for |
| {{{https://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration}reporting output files encoding}} |
| (defaults to <<<UTF-8>>>) |
| |
| [] |
| |
| [] |