Fork me on GitHub

flatten:flatten

Full name:

org.codehaus.mojo:flatten-maven-plugin:1.0.1:flatten

Description:

This MOJO realizes the goal flatten that generates the flattened POM and potentially updates the POM file so that the current MavenProject's file points to the flattened POM instead of the original pom.xml file. The flattened POM is a reduced version of the original POM with the focus to contain only the important information for consuming it. Therefore information that is only required for maintenance by developers and to build the project artifact(s) are stripped. Starting from here we specify how the flattened POM is created from the original POM and its project:
Element Transformation Note
modelVersion Fixed to "4.0.0" New maven versions will once be able to evolve the model version without incompatibility to older versions if flattened POMs get deployed.
groupId
artifactId
version
packaging
resolved copied to the flattened POM but with inheritance from parent as well as with all variables and defaults resolved. These elements are technically required for consumption.
licenses resolved copied to the flattened POM but with inheritance from parent as well as with all variables and defaults resolved. The licenses would not be required in flattened POM. However, they make sense for publication and deployment and are important for consumers of your artifact.
dependencies resolved specially flattened POM contains the actual dependencies of the project. Test dependencies are removed. Variables and dependencyManagement is resolved to get fixed dependency attributes (especially version). If embedBuildProfileDependencies is set to true, then also build-time driven Profiles will be evaluated and may add Dependency dependencies. For further details see Profiles below.
profiles resolved specially only the Activation and the Dependency dependencies of a Profile are copied to the flattened POM. If you set the parameter embedBuildProfileDependencies to true then only profiles Activation activated by JDK or OS will be added to the flattened POM while the other profiles are triggered by the current build setup and if activated their impact on dependencies is embedded into the resulting flattened POM.
name
description
url
inceptionYear
organization
scm
developers
contributors
mailingLists
pluginRepositories
issueManagement
ciManagement
distributionManagement
configurable Will be stripped from the flattened POM by default. You can configure all of the listed elements inside pomElements that should be kept in the flattened POM (e.g. <pomElements><name/><description/><developers/><contributors/></pomElements>). For common use-cases there are predefined modes available via the parameter flattenMode that should be used in preference.
prerequisites configurable Like above but by default NOT removed if packaging is "maven-plugin".
repositories configurable Like two above but by default NOT removed. If you want have it removed, you need to use the parameter pomElements and configure the child element repositories with value flatten.
parent
build
dependencyManagement
properties
modules
reporting
configurable These elements should typically be completely stripped from the flattened POM. However for ultimate flexibility (e.g. if you only want to resolve variables in a POM with packaging pom) you can also configure to keep these elements. We strictly recommend to use this feature with extreme care and only if packaging is pom (for "Bill of Materials"). In the latter case you configure the parameter flattenMode to the value bom.
If the build element contains plugins in the build/plugins section which are configured to load extensions, a reduced build element containing these plugins will be kept in the flattened pom.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency collection of artifacts in scope: runtime.
  • The goal is thread-safe and supports parallel builds.

Optional Parameters

Name Type Since Description
embedBuildProfileDependencies Boolean - Profiles activated by OS or JDK are valid ways to have different dependencies per environment. However, profiles activated by property of file are less clear. When setting this parameter to true, the latter dependencies will be written as direct dependencies of the project. This is not how Maven2 and Maven3 handles dependencies. When keeping this property false, all profiles will stay in the flattened-pom.
Default value is: false.
flattenMode FlattenMode - The different possible values for flattenMode:
Mode Description
oss For Open-Source-Software projects that want to keep all FlattenDescriptor optional POM elements except for repositories and pluginRepositories.
ossrh Keeps all FlattenDescriptor optional POM elements that are required for OSS Repository-Hosting.
bom Like ossrh but additionally keeps dependencyManagement and properties. Especially it will keep the dependencyManagement as-is without resolving parent influences and import-scoped dependencies. This is useful if your POM represents a BOM (Bill Of Material) and you do not want to deploy it as is (to remove parent and resolve version variables, etc.).
defaults The default mode that removes all FlattenDescriptor optional POM elements except repositories.
clean Removes all FlattenDescriptor optional POM elements.

flattenedPomFilename String - The filename of the generated flattened POM file.
Default value is: .flattened-pom.xml.
User property is: flattenedPomFilename.
outputDirectory File - The directory where the generated flattened POM file will be written to.
Default value is: ${project.basedir}.
pomElements FlattenDescriptor - The Model that defines how to handle additional POM elements. Please use flattenMode in preference if possible. This parameter is only for ultimate flexibility.
updatePomFile Boolean - The flag to indicate if the generated flattened POM shall be set as POM file to the current project. By default this is only done for projects with packaging other than pom. You may want to also do this for pom packages projects by setting this parameter to true or you can use false in order to only generate the flattened POM but never set it as POM file. If flattenMode is set to bom the default value will be true.
User property is: updatePomFile.

Parameter Details

embedBuildProfileDependencies:

Profiles activated by OS or JDK are valid ways to have different dependencies per environment. However, profiles activated by property of file are less clear. When setting this parameter to true, the latter dependencies will be written as direct dependencies of the project. This is not how Maven2 and Maven3 handles dependencies. When keeping this property false, all profiles will stay in the flattened-pom.
  • Type: java.lang.Boolean
  • Required: No
  • Default: false

flattenMode:

The different possible values for flattenMode:
Mode Description
oss For Open-Source-Software projects that want to keep all FlattenDescriptor optional POM elements except for repositories and pluginRepositories.
ossrh Keeps all FlattenDescriptor optional POM elements that are required for OSS Repository-Hosting.
bom Like ossrh but additionally keeps dependencyManagement and properties. Especially it will keep the dependencyManagement as-is without resolving parent influences and import-scoped dependencies. This is useful if your POM represents a BOM (Bill Of Material) and you do not want to deploy it as is (to remove parent and resolve version variables, etc.).
defaults The default mode that removes all FlattenDescriptor optional POM elements except repositories.
clean Removes all FlattenDescriptor optional POM elements.
  • Type: org.codehaus.mojo.flatten.FlattenMode
  • Required: No

flattenedPomFilename:

The filename of the generated flattened POM file.
  • Type: java.lang.String
  • Required: No
  • User Property: flattenedPomFilename
  • Default: .flattened-pom.xml

outputDirectory:

The directory where the generated flattened POM file will be written to.
  • Type: java.io.File
  • Required: No
  • Default: ${project.basedir}

pomElements:

The Model that defines how to handle additional POM elements. Please use flattenMode in preference if possible. This parameter is only for ultimate flexibility.
  • Type: org.codehaus.mojo.flatten.FlattenDescriptor
  • Required: No

updatePomFile:

The flag to indicate if the generated flattened POM shall be set as POM file to the current project. By default this is only done for projects with packaging other than pom. You may want to also do this for pom packages projects by setting this parameter to true or you can use false in order to only generate the flattened POM but never set it as POM file. If flattenMode is set to bom the default value will be true.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: updatePomFile