Maven Profile

From NovaOrdis Knowledge Base
Jump to: navigation, search

External

Internal

Overview

A profile is an alternative set of configurations which set or override default values. Profiles allow to customize a build for different environments. Profiles can be defined:

  • per project in the pom.xml file. These are called inline profiles and they are preferred, as they have a better chance of preserving the portability.
  • per-user in ${user.home}/.m2/settings.xml. These are a truncated version of the inline profile, only containing <activation>, <repositories>, <pluginRepositories> and <properties> elements. They are truncated because they concern themselves with the build system as a whole, not about individual project object model setting. Note that if a profile is active from settings.xml, its values will override any equivalently ID'd profiles in a POM or profiles.xml.
  • global in ${maven.home}/conf/settings.xml

Each profile is identified with an identifier. Profiles customizes the build for different environments (e.g. production or development, different operating systems, different JDK versions, etc.)

The power of a profile comes from its ability to modify some values only under certain circumstances. Those circumstances can be specified in a variety of ways - see Activating a Profile below.

An example of profile:

...
<profiles> 
   <profile>
     <id>production</id>
     <build>
        <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              <configuration>
                  <debug>false</debug> 
                  <optimize>true</optimize>
              </configuration>
            </plugin>
        </plugins>
     </build>
     <repositories>
         <repository>
             <id>some-repository</id>
             <name>Some Repository</name>
             <url>file:////some/maven-repository/</url>
             <layout>default</layout>
         </repository>
     </repositories>
   </profile>
 </profiles>
...

Examples

https://github.com/NovaOrdis/playground/blob/master/jboss/infinispan/hotrod-client/pom.xml

Active Profile

More than one profile can be active at a time. A profile can be "activated" by declaring it so (see Active by Default below) or by specifying it in the list of active profiles in settings.xml, or via other methods. For more details see Activating a Profile below.

How Can I Tell which Profile is Active?

mvn help:active-profiles

Effective Settings when More than One Profile is Active

TODO

Profile Naming Conventions

Use the common system property trigger as part of the name for the profile. If a profile is triggered by the system property env, valid profile names are env-dev, env-stage, etc.

A profile ID may include spaces.

Build Configuration that Can Be Modified in a Profile

Inline Profiles

An inline profile can modify the following POM elements:

  • <repositories>
  • <pluginRepositories>
  • <dependencies>
  • <plugins>
  • <properties> (not actually available in the main POM, but used behind the scenes, for more details see section "Profiles and Properties")
  • <modules>
  • <reporting>
  • <dependencyManagement>
  • <distributionManagement>
  • a subset of the <build> element, which consists of:
    • <defaultGoal>
    • <resources>
    • <testResources>
    • <finalName>

Profiles and Properties

<profile>
    <properties>
       <some.property>...</some.property>
    </properties>
</profile>

The properties declared as such are accessible form a POM if the declaring profile is active.

Also see:

Maven Concepts - Variables

Standard Properties

Download Sources for all Dependencies

<profile>
  <id>...</id>
  <properties>
      <downloadSources>true</downloadSources>
  </properties>
  ...
</profile>
Also see
Download Sources with the Class JAR Files

Download Javadoc for all Dependencies

<profile>
  <id>...</id>
  <properties>
      <downloadJavadocs>true</downloadJavadocs>
  </properties>
  ...
</profile>

Activating a Profile

Active by Default

<profile>
    <id>some-profile</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
   ...
</profile>

Command Line

The profile can be activated explicitly on command line with -P:

mvn -Pproduction clear install

When this options is used, the specified profiles are activated in additions of those specified in the <activeProfiles> element of settings.xml.

In Settings

The active profiles are specified in settings.xml:

<settings>
  ...
  <activeProfiles>
    <activeProfile>blue</activeProfile>
  </activeProfiles>
  ...
</settings>

The list contains <activeProfile> elements, where each element contains a profile id. Any profile referred here will be active regardless of any environment settings. If no matching profile is found, nothing will happen. If the profiles mentioned here are not found, the execution will continue as normal.

By a System Property

mvn -Denv=test ...

Other Methods

A profile can also be triggered based on environment variables, OS settings, or present or missing files. The trigger is specified in the <activation> section of the profile. Activation occurs when all specified criteria have been met.

Example:

<activation>
    <activeByDefault>false</activeByDefault>
    <jdk>1.5</jdk>
    <os>
         <name>Windows XP</name>
         <family>Windows</family>
         <arch>x86</arch>
         <version>5.1.2600</version>
    </os> 
    <property>
        <name>mavenVersion</name>
        <value>2.0.3</value> 
    </property>
    <file>
         <exists>${basedir}/file2.properties</exists>
         <missing>${basedir}/file1.properties</missing> 
    </file>
</activation>

For more details, see:

maven-enforcer-plugin