Skip to content

[MNGSITE-515] Update introduction to profiles #1490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bukama wants to merge 6 commits into
base: master
Choose a base branch
from
Open

[MNGSITE-515] Update introduction to profiles #1490

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3a16189
[MNGSITE-515] Mentioned profile properties
Bukama Dec 15, 2025
e770c88
Feedback
Bukama Dec 26, 2025
87197cb
Feedback
Bukama Dec 26, 2025
a0137fa
Feedback
Bukama Dec 26, 2025
bfd89d6
Feedback
Bukama Dec 29, 2025
589f714
Feedback
Bukama Jan 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 93 additions & 11 deletions content/markdown/guides/introduction/introduction-to-profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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.
Copy link
Contributor

@elharo elharo Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be better as an absolute URL in case this site is mirrored somewhere


##### 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:

Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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>`
Expand All @@ -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 &lt;profiles&gt;

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.
Expand Down
107 changes: 9 additions & 98 deletions content/markdown/pom.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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)

Expand Down
Loading