Details on profile activation

mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3

<settings>
  ...
  <activeProfiles>
    <activeProfile>profile-1</activeProfile>
  </activeProfiles>
  ...
</settings>

<profiles>
  <profile>
    <id>profile-1</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <jdk>1.4</jdk>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <jdk>[1.3,1.6)</jdk>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <os>
        <name>Windows XP</name>
        <family>Windows</family>
        <arch>x86</arch>
        <version>5.1.2600</version>
      </os>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <property>
        <name>debug</name>
      </property>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <property>
        <name>!debug</name>
      </property>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <property>
        <name>debug</name>
        <value>!true</value>
      </property>
    </activation>
    ...
  </profile>
</profiles>

mvn groupId:artifactId:goal
mvn groupId:artifactId:goal -Ddebug=false

<profiles>
  <profile>
    <activation>
      <property>
        <name>environment</name>
        <value>test</value>
      </property>
    </activation>
    ...
  </profile>
</profiles>

mvn groupId:artifactId:goal -Denvironment=test

<profiles>
  <profile>
    <activation>
      <property>
        <name>packaging</name>
        <value>war</value>
      </property>
    </activation>
    ...
  </profile>
</profiles>

<profiles>
  <profile>
    <activation>
      <file>
        <missing>target/generated-sources/axistools/wsdl2java/org/apache/maven</missing>
      </file>
    </activation>
    ...
  </profile>
</profiles>

Deactivating a profile

One or more profiles can be deactivated using the command line by prefixing their identifier with either the character '!' or '-' as shown below.

Note that ! needs to be escaped with \ or quoted in Bash, ZSH and other shells as it has a special meaning. Also there is a known bug with command line option values starting with - (CLI-309), therefore it is recommended to use it with the syntax -P=-profilename.

mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3

or

mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3

This can be used to deactivate profiles marked as activeByDefault or profiles that would otherwise be activated through their activation config.

Profiles in external files

Profiles specified in external files (i.e in settings.xml or profiles.xml) are not portable in the strictest sense. Anything that seems to stand a high chance of changing the result of the build is restricted to the inline profiles in the POM. Things like repository lists could simply be a proprietary repository of approved artifacts, and won't change the outcome of the build. Therefore, you will only be able to modify the <repositories> and <pluginRepositories> sections, plus an extra <properties> section.

The <properties> section allows you to specify free-form key-value pairs which will be included in the interpolation process for the POM. This allows you to specify a plugin configuration in the form of ${profile.provided.path}.

Profiles in POMs

On the other hand, if your profiles can be reasonably specified inside the POM, you have many more options. The trade-off, of course, is that you can only modify that project and its sub-modules. Since these profiles are specified inline, and therefore have a better chance of preserving portability, it's reasonable to say you can add more information to them without the risk of that information being unavailable to other users.

Profiles specified in the POM can modify the following POM elements:

• <repositories>
• <pluginRepositories>
• <dependencies>
• <plugins>
• <properties> (not actually available in the main POM, but used behind the scenes)
• <modules>
• <reports>
• <reporting>
• <dependencyManagement>
• <distributionManagement>
• a subset of the <build> element, which consists of:
  • <defaultGoal>
  • <resources>
  • <testResources>
  • <directory>
  • <finalName>
  • <filters>
  • <pluginManagement>
  • <plugins>

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.

External files such as settings.xml and profiles.xml also do not support elements outside the POM-profiles. Let us take this scenario for elaboration. When the effective POM is deployed to a remote repository, any person can pickup its info out of the repository and use it to build a Maven project directly. Now, imagine that if we can set profiles in dependencies, which is very important to a build, or in any other elements outside POM-profiles in settings.xml then most probably we cannot expect someone else to use that POM from the repository and be able to build it. And we have to also think about how to share the settings.xml with others. Note that too many files to configure are very confusing and very hard to maintain. Bottom line is that since this is build data, it should be in the POM.

External Properties

External property definition concerns any property value defined outside the pom.xml but not defined in a corresponding profile inside it. The most obvious usage of properties in the POM is in plugin configuration. While it is certainly possible to break project portability without properties, these critters can have subtle effects that cause builds to fail. For example, specifying appserver paths in a profile that is specified in the settings.xml may cause your integration test plugin to fail when another user on the team attempts to build without a similar settings.xml. Consider the following pom.xml snippet for a web application project:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.myco.plugins</groupId>
        <artifactId>spiffy-integrationTest-plugin</artifactId>
        <version>1.0</version>
        <configuration>
          <appserverHome>${appserver.home}</appserverHome>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Now, in your local ${user.home}/.m2/settings.xml, you have:

<settings>
  ...
  <profiles>
    <profile>
      <id>appserverConfig</id>
      <properties>
        <appserver.home>/path/to/appserver</appserver.home>
      </properties>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>appserverConfig</activeProfile>
  </activeProfiles>
  ...
</settings>

When you build the integration-test lifecycle phase, your integration tests pass, since the path you've provided allows the test plugin to install and test this web application.

However, when your colleague attempts to build to integration-test, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter <appserverHome>, or worse, that the value of that parameter - literally ${appserver.home} - is invalid (if it warns you at all).

Congratulations, your project is now non-portable. Inlining this profile in your pom.xml can help alleviate this, with the obvious drawback that each project hierarchy (allowing for the effects of inheritance) now have to specify this information. Since Maven provides good support for project inheritance, it's possible to stick this sort of configuration in the <pluginManagement> section of a team-level POM or similar, and simply inherit the paths.

Another, less attractive answer might be standardization of development environments. However, this will tend to compromise the productivity gain that Maven is capable of providing.

Incomplete Specification of a Natural Profile Set

In addition to the above portability-breaker, it's easy to fail to cover all cases with your profiles. When you do this, you're usually leaving one of your target environments high and dry. Let's take the example pom.xml snippet from above one more time:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.myco.plugins</groupId>
        <artifactId>spiffy-integrationTest-plugin</artifactId>
        <version>1.0</version>
        <configuration>
          <appserverHome>${appserver.home}</appserverHome>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Now, consider the following profile, which would be specified inline in the pom.xml:

<project>
  ...
  <profiles>
    <profile>
      <id>appserverConfig-dev</id>
      <activation>
        <property>
          <name>env</name>
          <value>dev</value>
        </property>
      </activation>
      <properties>
        <appserver.home>/path/to/dev/appserver</appserver.home>
      </properties>
    </profile>

    <profile>
      <id>appserverConfig-dev-2</id>
      <activation>
        <property>
          <name>env</name>
          <value>dev-2</value>
        </property>
      </activation>
      <properties>
        <appserver.home>/path/to/another/dev/appserver2</appserver.home>
      </properties>
    </profile>
  </profiles>
  ..
</project>

This profile looks quite similar to the one from the last example, with a few important exceptions: it's plainly geared toward a development environment, a new profile named appserverConfig-dev-2 is added and it has an activation section that will trigger its inclusion when the system properties contain "env=dev" for a profile named appserverConfig-dev and "env=dev-2" for a profile named appserverConfig-dev-2. So, executing:

mvn -Denv=dev-2 integration-test

will result in a successful build, applying the properties given by profile named appserverConfig-dev-2. And when we execute

mvn -Denv=dev integration-test

it will result in a successful build applying the properties given by the profile named appserverConfig-dev. However, executing:

mvn -Denv=production integration-test

will not do a successful build. Why? Because, the resulting non-interpolated literal value of ${appserver.home} will not be a valid path for deploying and testing your web application. We haven't considered the case for the production environment when writing our profiles. The "production" environment (env=production), along with "test" and possibly even "local" constitute a natural set of target environments for which we may want to build the integration-test lifecycle phase. The incomplete specification of this natural set means we have effectively limited our valid target environments to the development environment. Your teammates - and probably your manager - will not see the humor in this. When you construct profiles to handle cases such as these, be sure to address the entire set of target permutations.

As a quick aside, it's possible for user-specific profiles to act in a similar way. This means that profiles for handling different environments which are keyed to the user can act up when the team adds a new developer. While I suppose this could act as useful training for the newbie, it just wouldn't be nice to throw them to the wolves in this way. Again, be sure to think of the whole set of profiles.