Profiles and their activation
A profile is a block of a pom that is part of the model only when something turns it on. It can hold properties, dependencies, plugins, repositories, and even a module list, which makes it the tool for the differences between a developer machine, a test environment and a release. This article writes two profiles, turns them on in the two ways a command line offers, and reads the value each one puts into the build.
The project
One property, app.env, whose value the two profiles change; one filtered resource that prints it; and the profiles at the end of the pom. dev has to be asked for by its id, prod turns itself on when the property env has the value prod.
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>profiles-demo</artifactId>
<version>1.0.0</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<app.env>none</app.env>
</properties>
<build>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</build>
<profiles>
<profile>
<id>dev</id>
<properties>
<app.env>dev</app.env>
</properties>
</profile>
<profile>
<id>prod</id>
<activation>
<property>
<name>env</name>
<value>prod</value>
</property>
</activation>
<properties>
<app.env>prod</app.env>
</properties>
</profile>
</profiles>
</project>
src/main/resources/env.properties
env=${app.env}
Which profile is active
help:active-profiles lists the profiles of the build, with the source each one was activated by. Without a switch there is no active profile here, and the goal says so with an empty list:
mvn -B help:active-profiles > none.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" none.log
Active Profiles for Project 'com.example:profiles-demo:jar:1.0.0':
The following profiles are active:
-Pdev turns the first one on. The id in the parentheses is the coordinates of the pom the profile comes from, which matters when a parent or a settings file has profiles of its own:
mvn -B help:active-profiles -Pdev > dev.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" dev.log
Active Profiles for Project 'com.example:profiles-demo:jar:1.0.0':
The following profiles are active:
- dev (source: com.example:profiles-demo:1.0.0)
The second one has no id on the command line: it activates itself from the property env, which the switch -Denv=prod sets. Maven checks the activation of every profile after it has the properties, so the order of the switches on the command line does not matter.
mvn -B help:active-profiles -Denv=prod > prod.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" prod.log
Active Profiles for Project 'com.example:profiles-demo:jar:1.0.0':
The following profiles are active:
- prod (source: com.example:profiles-demo:1.0.0)
The value it changes
A profile that changes nothing is hard to see, so the resource prints the value. With -Pdev the filtered copy has the value of the profile:
mvn -B -q -Pdev package; echo "status: $?"; cat target/classes/env.properties
status: 0
env=dev
Without the profile the property keeps the value the pom gives it, which is none:
mvn -B -q clean package; echo "status: $?"; cat target/classes/env.properties
status: 0
env=none
The clean in the second command is not decoration: the first build left a filtered copy in target/classes, and the resources plugin does not filter a file whose copy is newer than the source. Without the clean, the second command would leave the old value in place and the reading would be of the first build.
How a profile is activated
Five ways, checked in this order, and a profile is on if any of them says so:
- -P<id> on the command line, which also takes a list (-Pdev,prod) and a negation (-P!prod).
- An explicit property, with <activation><property> and a name, a value or both, as the second profile here.
- The JDK: a version or a range, so a project can add a module or an argument only on Java 21 and newer.
- The operating system: a family such as unix and an architecture, which is how a profile adds a native library for one platform.
- A file, present or missing: .mvn/maven.config and a local.properties are the two usual ones.
A profile marked <activeByDefault>true</activeByDefault> is active only when nothing else activated any profile of that pom, which is a rule that surprises people: adding -Pdev turns the default profile off. Profiles can also live in settings.xml, where they add repositories and properties but cannot add a dependency of a project.
A profile is a part of the model, not a script: it cannot run a command or change a value outside the model, and everything it adds is merged exactly like the blocks of the pom itself. The effective pom of a build started with -Pdev shows the merged result, with the profile block gone.
Where to go next
settings.xml, mirrors and the repository location opens the other file Maven reads, the one of a machine rather than of a project.
Article author: Arthur Isaev