This is an automated email from the ASF dual-hosted git repository.
mbuenger pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new a210ace0 [MNGSITE-515] Update introduction to profiles (#1490)
a210ace0 is described below
commit a210ace00136ff5eeb9a87ee4706825fb5cab140
Author: Matthias Bünger <[email protected]>
AuthorDate: Sat Jan 10 10:49:30 2026 +0100
[MNGSITE-515] Update introduction to profiles (#1490)
This PR removes almost the entire examples about `<profiles>` of the POM
reference and integrates them into the profile guide to avoid duplication and
inconsistent content.
Some missing or unclear parts were also added to the guide (as requested in
the issue).
closes #873
---
.../introduction/introduction-to-profiles.md | 104 +++++++++++++++++---
content/markdown/pom.md | 107 ++-------------------
2 files changed, 102 insertions(+), 109 deletions(-)
diff --git a/content/markdown/guides/introduction/introduction-to-profiles.md
b/content/markdown/guides/introduction/introduction-to-profiles.md
index b4674414..ef08d009 100644
--- a/content/markdown/guides/introduction/introduction-to-profiles.md
+++ b/content/markdown/guides/introduction/introduction-to-profiles.md
@@ -19,7 +19,7 @@ under the License.
# Introduction to Build Profiles
-<!-- MACRO{toc|section=0|fromDepth=2|toDepth=5} -->
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=6} -->
Apache Maven goes to great lengths to ensure that builds are portable. Among
other things, this means allowing build configuration inside the POM, avoiding
**all** filesystem references (in inheritance, dependencies, and other places),
and leaning much more heavily on the local repository to store the metadata
needed to make this possible.
@@ -53,7 +53,7 @@ A profile can be activated in several ways:
- Implicitly, based on
- JDK version
- Operating system
- - system properties
+ - system or CLI user properties
- packaging properties
- presence of files
@@ -106,7 +106,25 @@ This profile will automatically be active for all builds
unless another profile
Profiles can be automatically triggered based on the state of the build
environment.
These triggers are specified via an `<activation>` section in the profile.
The implicit profile activation only refers to the container profile (and not
to profiles in other modules with the same id).
-Here are some examples.
+The activation occurs when all the specified criteria have been met.
+
+##### Active by default
+
+Boolean flag which determines if the profile is active by default. Is `false`
by default.
+This flag is only evaluated if no other profile is explicitly activated via
command line, `settings.xml` or activated through some other activator.
Otherwise, it has no effect.
+
+Example to set a profile active by default.
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
##### JDK
@@ -123,7 +141,8 @@ The following configuration will trigger the profile when
the JDK's version _sta
</profiles>
```
-[Ranges](/enforcer/enforcer-rules/versionRanges.html) can also be used. Range
values must start with either `[` or `(`. Otherwise, the value is interpreted
as a prefix. The following honours versions `1.3`, `1.4` and `1.5`.
+[Ranges](/enforcer/enforcer-rules/versionRanges.html) can also be used. Range
values must start with either `[` or `(`.
+The following honours versions `1.3`, `1.4`, and `1.5`.
```xml
<profiles>
@@ -136,11 +155,28 @@ The following configuration will trigger the profile when
the JDK's version _sta
</profiles>
```
-_Note:_ an upper bound such as `,1.5]` is likely not to include most releases
of 1.5, since they will have an additional "patch" release such as `_05` that
is not taken into consideration in the above range.
+_Note:_ The value ranges match if the JDK version used for running Maven is
between the lower and upper bounds (either inclusive or exclusive).
+An upper bound such as `,1.5]` likely does not include most releases of 1.5,
since they will have an additional "patch" release such as `_05` that is not
taken into consideration in the above range.
+
+If the range does not start with `[` or `(`, the value is interpreted as a
vendor prefix.
+A prefix is negated if the value starts with `!`.
+(Negated) prefix values match if the JDK version used for running Maven
starts/doesn't start with the given prefix (excluding the potentially leading
`!`).
+The following profile would be active, when any `zulu64` JDK is used.
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <jdk>zulu64</jdk>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
##### OS
-This next one will activate based on the detected operating system. See the
[Maven Enforcer Plugin](/enforcer/enforcer-rules/requireOS.html) for more
details about OS values.
+This next one will activate based on the detected operating system. See the
[Maven Enforcer
Plugin](https://maven.apache.org/enforcer/enforcer-rules/requireOS.html) for
more details about OS values.
```xml
<profiles>
@@ -165,8 +201,16 @@ Each value can be prefixed with `!` to negate the
matching. The values match if
Since [Maven 3.9.7](https://issues.apache.org/jira/browse/MNG-5726) the value
for `version` may be prefixed with `regex:`. In that case [regular pattern
matching](https://docs.oracle.com/javase/tutorial/essential/regex/) is applied
for the version matching and applied against the **lower case** `os.version`
value.
The actual OS values which need to match the given values are emitted when
executing `mvn --version`.
+See the maven-enforcer-plugin's [Require OS
Rule](/enforcer/enforcer-rules/requireOS.html) for more details about OS values.
+
+##### Properties
+
+The `profile` will activate if Maven detects a system property or CLI user
property (a value which can be dereferenced within the POM by `${name}`) of the
corresponding `name=value` pair, and it matches the given value (if given).
+Since Maven 3.9.0 one can also evaluate the `<packaging value>` of the pom via
property name `packaging`.
-##### System Property
+###### System or CLI user property
+The `profile` will activate if Maven detects a system property or CLI user
property (a value which can be dereferenced within the POM by `${name}`)
+of the corresponding `name=value` pair, and it matches the given value (if
given).
The profile below will be activated when the system property `debug` is
specified with any value:
@@ -270,7 +314,7 @@ Profiles in the POM can also be activated based on
properties from active profil
**Note**: Environment variables like `FOO` are available as properties of the
form `env.FOO`. Further note that environment variable names are normalized to
all upper-case on Windows.
-#### Packaging property
+###### Packaging property
Since Maven 3.9.0 one can also evaluate the POM's packaging value by
referencing property `packaging`. This is only useful where the profile
activation is defined in a common parent POM which is reused among multiple
Maven projects. The next example will trigger the profile when a project with
packaging `war` is built:
@@ -290,6 +334,9 @@ Since Maven 3.9.0 one can also evaluate the POM's packaging
value by referencing
##### Files
+A given filename may activate the `profile` by the `existence` of a file, or
if it is `missing`.
+**NOTE**: Interpolation for this element is limited to `${project.basedir}`,
System properties, and request properties.
+
This example will trigger the profile when the generated file
`target/generated-sources/axistools/wsdl2java/org/apache/maven` is missing.
```xml
@@ -309,7 +356,7 @@ The tags `<exists>` and `<missing>` can be interpolated.
Supported variables are
#### Multiple conditions
-Different implicit activation types can be combined in one profile. The
profile is then only active if all conditions are met (since Maven 3.2.2,
[MNG-4565](https://issues.apache.org/jira/browse/MNG-4565)). Using the same
type more than once in the same profile is not supported
([MNG-5909](https://issues.apache.org/jira/browse/MNG-5909),
[MNG-3328](https://issues.apache.org/jira/browse/MNG-3328)).
+Different implicit activation types can be combined in one profile. The
profile is then only active if all conditions are met. Using the same type more
than once in the same profile is not supported
([MNG-5909](https://issues.apache.org/jira/browse/MNG-5909),
[MNG-3328](https://issues.apache.org/jira/browse/MNG-3328)).
### Deactivating a profile
@@ -351,13 +398,13 @@ Profiles specified in the POM can modify [the following
POM elements](/ref/curre
- `<pluginRepositories>`
- `<dependencies>`
- `<plugins>`
-- `<properties>` (not actually available in the main POM, but used behind the
scenes)
+- `<properties>`
- `<modules>`
- `<reports>`
- `<reporting>`
- `<dependencyManagement>`
- `<distributionManagement>`
-- a subset of the `<build>` element, which consists of:
+- the following subset of the `<build>` element:
- `<defaultGoal>`
- `<resources>`
- `<testResources>`
@@ -367,6 +414,41 @@ Profiles specified in the POM can modify [the following
POM elements](/ref/curre
- `<pluginManagement>`
- `<plugins>`
+_Note_: A profile which tries to modify other elements of the `<build>`
element is invalid and will fail the build with a "malformed POM" error.
+
+#### Examples
+
+The following example defines a profile to execute the [Maven Invoker
Plugin](https://maven.apache.org/plugins/maven-invoker-plugin/):
+
+```xml
+<profile>
+ <id>run-its</id>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-invoker-plugin</artifactId>
+ <configuration>
+ <goals>
+ <goal>clean</goal>
+ <goal>package</goal>
+ </goals>
+ </configuration>
+ <executions>
+ <execution>
+ <id>integration-test</id>
+ <goals>
+ <goal>install</goal>
+ <goal>integration-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</profile>
+```
+
### POM elements outside <profiles>
We don't allow modification of some POM elements outside of POM-profiles
because these runtime modifications will not be distributed when the POM is
deployed to the repository system, making that person's build of that project
completely unique from others. While you can do this to some extent with the
options given for external profiles, the danger is limited. Another reason is
that this POM info is sometimes being reused from the parent POM.
diff --git a/content/markdown/pom.md b/content/markdown/pom.md
index 50e4c3a4..862bc4bb 100644
--- a/content/markdown/pom.md
+++ b/content/markdown/pom.md
@@ -1957,20 +1957,19 @@ to the repository. It is described here just for
understanding, but should never
## Profiles
-A new feature of the POM 4.0 is the ability of a project to change settings
depending
-on the environment where it is being built. A `profile` element contains both
an optional
-activation (a profile trigger) and the set of changes to be made to the POM if
that profile has been
-activated. For example, a project built for a test environment may point to a
different database than
-that of the final deployment. Or dependencies may be pulled from different
repositories based upon
-the JDK version used.
-The elements of profiles are as follows:
+Profiles offer the possibility to change project settings depending on the
environment where it is being built.
+For example, a project built for a test environment may point to a different
database than that of the final deployment.
+Or dependencies may be pulled from different repositories based upon the JDK
version used.
+
+The elements of profiles are as follows.
+All elements are optional.
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0";>
...
<profiles>
<profile>
- <id>test</id>
+ <id>...</id>
<activation>...</activation>
<build>...</build>
<modules>...</modules>
@@ -1980,101 +1979,13 @@ The elements of profiles are as follows:
<reporting>...</reporting>
<dependencyManagement>...</dependencyManagement>
<distributionManagement>...</distributionManagement>
+ <properties>...</properties>
</profile>
</profiles>
</project>
```
-### Activation
-
-Activations are the key of a profile. The power of a profile comes from its
ability to modify the
-basic POM only under certain circumstances. Those circumstances are specified
via an `activation` element.
-
-```xml
-<project xmlns="http://maven.apache.org/POM/4.0.0";>
- <!-- ... -->
- <profiles>
- <profile>
- <id>test</id>
- <activation>
- <activeByDefault>false</activeByDefault>
- <jdk>21</jdk>
- <os>
- <name>Windows 10</name>
- <family>Windows</family>
- <arch>amd64</arch>
- <version>10.0.19045.5247</version>
- </os>
- <property>
- <name>sparrow-type</name>
- <value>African</value>
- </property>
- <file>
- <exists>${project.basedir}/file2.properties</exists>
- <missing>${project.basedir}/file1.properties</missing>
- </file>
- </activation>
- <!-- ... -->
- </profile>
- </profiles>
-</project>
-```
-
-Before Maven 3.2.2 activation occurs when one or more of the specified
criteria have been met. When the first positive result is encountered,
processing stops and the profile is marked as active.
-Since Maven 3.2.2 activation occurs when all the specified criteria have been
met.
-
-* `<activeByDefault>`:
- Is `false` by default. Boolean flag which determines if the profile is
active by default. This flag is only evaluated if no other profile is
explicitly activated via command line, `settings.xml` or implicitly activated
through some other activator, otherwise it has no effect.
-
-* `<jdk>`:
- `activation` has a built-in, Java-centric check in the `jdk` element. The
value is one of the following three types:
-
- * A version range according to the definition of [Maven Enforcer
Plugin](/enforcer/enforcer-rules/versionRanges.html) in case the value starts
with either `[` or `(`,
-
- * A negated prefix if the value starts with `!` or
-
- * A (non-negated) prefix for all other cases
-
- (Negated) prefix values match if the JDK version used for running Maven
starts/doesn't start with the given prefix (excluding the potentially leading
`!`).
- The value ranges match if the JDK version used for running Maven is between
lower and upper bounds (either inclusive or exclusive).
-
-* `<os>`:
- The `os` element can require some operating system specific properties
having specific values.
- Each value may start with `!` which means the condition is fulfilled if the
value following does **not** equal the actual value,
- otherwise the condition is fulfilled if the value equals the according
system property (or derived value). In both cases the check is `<case
insensitive>`.
-
- * `<name>`, is matched against system property `os.name`
-
- * `<family>`, is matched against the family derived from the other `<os.*>`
system properties
-
- * `<arch>`, is matched against system property `os.arch`
-
- * `<version>`, is matched against system property `os.version`. Since [Maven
3.9.7](https://issues.apache.org/jira/browse/MNG-5726)
- the value for `version` may be prefixed with `regex:`. In that case
[regular pattern
matching](https://docs.oracle.com/javase/tutorial/essential/regex/) is applied
for the version matching. Note that system property `os.version` is converted
to `<lower case>` prior to the matching.
-
-See the maven-enforcer-plugin's [Require OS
Rule](/enforcer/enforcer-rules/requireOS.html) for more details about OS values.
-
-* `<property>`:
- The `profile` will activate if Maven detects a system property or CLI user
property (a value which can be dereferenced within the POM by `${name}`)
- of the corresponding `name=value` pair, and it matches the given value (if
given). Since Maven 3.9.0 one can also evaluate the `<packaging value>` of the
pom via property name `packaging`.
-
-* `<file>`:
- Finally, a given filename may activate the `profile` by the `existence` of a
file, or if it
- is `missing`. **NOTE**: interpolation for this element is limited to
`${project.basedir}`, System properties and request properties.
-
-The POM based profile activation only refers to the container profile (not all
profiles with the same `id`).
-
-The `activation` element is not the only way that a `profile` may be activated.
-The `settings.xml` file's `activeProfile` element may contain the profile's
`id`. They may also be
-activated explicitly through the command line via a comma separated list after
the `-P` flag (e.g. `-P codecoverage`).
-
-*To see which profile will activate in a certain build, use the*
`maven-help-plugin`.
-
-```
-mvn help:active-profiles
-```
-
-Further information about profiles is available in [Introduction to Build
Profiles](./guides/introduction/introduction-to-profiles.html).
+Extensive information about profiles, including examples, are available in
[Introduction to Build
Profiles](./guides/introduction/introduction-to-profiles.html).
## The BaseBuild Element Set (revisited)
