You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by ar...@apache.org on 2006/02/09 09:41:41 UTC
svn commit: r376222 -
/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt
Author: aramirez
Date: Thu Feb 9 00:41:40 2006
New Revision: 376222
URL: http://svn.apache.org/viewcvs?rev=376222&view=rev
Log:
PR: MNG-2000
-added info into the build profiles document.
Modified:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt
Modified: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt
URL: http://svn.apache.org/viewcvs/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt?rev=376222&r1=376221&r2=376222&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt (original)
+++ maven/site/trunk/src/site/apt/guides/introduction/introduction-to-profiles.apt Thu Feb 9 00:41:40 2006
@@ -1,9 +1,9 @@
---
Introduction to build profiles
---
- 30-July-2005
+ 05-Feb-2006
---
- John Casey
+ John Casey/Allan Ramirez
---
Introduction to Build Profiles
@@ -30,24 +30,32 @@
in the development, testing, and production environments). As such, profiles
can easily lead to differing build results from different members of your team.
However, used properly, profiles can be used while still preserving
- project portability.
+ project portability. This will also minimize the use of <<<-f>>> option of
+ maven which allows user to create another POM with different parameters or
+ configuration to build which makes it more maintainable since it is runnning
+ with one POM only.
-* Profile Locations
+* What are the different types of profile? Where is each defined?
- Build profiles can be specified in any of three locations:
-
- * the Maven settings file
+ * Per Project
+
+ - Defined in the POM itself <<<(pom.xml)>>>.
- * a file in the the project basedir called <<<profiles.xml>>>
+ * Per User
- * in the POM itself
+ - Defined in the Maven-settings <<<(%USER_HOME%/.m2/settings.xml)>>>.
+
+ * Global
+
+ - Defined in the global maven-settings <<<(%M2_HOME%/conf/settings.xml)>>>.
+
+ * Profile descriptor
- As we'll discuss later, the location of the profile determines what parameters
- of the POM it can modify.
+ - a descriptor located in project basedir <<<(profiles.xml)>>>
-* Triggering Profiles
+* How can a profile be triggered? How does this vary according to the type of profile being used?
- Profile triggering also happens in one of three general ways:
+ A profile can be triggered/activated in several ways:
* Profiles can be explicitly specified using the <<<-P>>> CLI option.
@@ -55,10 +63,26 @@
profile-ids to be used. When this option is specified, no profiles other
than those specified in the option argument will be activated.
++---+
+mvn groupId:artifactId:goal -P profile-1,profile-2
++---+
+
* Profiles can be activated in the Maven settings, via the <<activeProfiles>>
section. This section takes a list of <<activeProfile>> elements, each
containing a profile-id inside.
++---+
+<settings>
+ ...
+ <activeProfiles>
+ <activeProfile>profile-1</activeProfile>
+ </activeProfiles>
+</settings>
++---+
+
+ Profiles listed in the <activeProfiles> tag would be activated by default
+ everytime a project use it.
+
* Profiles can be automatically triggered based on the detected state of
the build environment. These triggers are specified via an <<activation>>
section in the profile itself. Currently, this detection is limited to
@@ -66,38 +90,53 @@
the value of a system property. Here are some examples:
+---+
-<activation>
- <jdk>1.4</jdk>
-</activation>
+<profiles>
+ <profile>
+ <activation>
+ <jdk>1.4</jdk>
+ </activation>
+ ...
+ </profile>
+</profiles>
+---+
This will trigger the profile when the JDK's version starts with "1.4" (eg.
"1.4.0_08", "1.4.2_07", "1.4").
+---+
-<activation>
- <property>
- <name>debug</name>
- </property>
-</activation>
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>debug</name>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+---+
This will activate the profile when the system property "debug" is specified
with any value.
+---+
-<activation>
- <property>
- <name>environment</name>
- <value>test</value>
- </property>
-</activation>
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>environment</name>
+ <value>test</value>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+---+
This last example will trigger the profile when the system property
"environment" is specified with the value "test".
-* What Can I Configure in a Profile?
+* Which areas of a POM can be customized by each type of profile? Why?
Now that we've talked about where to specify profiles, and how to activate them,
it will be useful to talk about <what> you can specify in a profile. As with
@@ -106,11 +145,12 @@
Depending on where you choose to configure your profile, you will have access
to varying POM configuration options. Profiles specified in external files
(i.e in <<<settings.xml>>> or <<<profiles.xml>>>) are not portable in the
- strictest sense, because they externalize some of the build configuration from
- the only project metadata that is maintained on the remote repositories: the
- POM. Therefore, you will only be able to modify the <<repositories>> and
- <<pluginRepositories>> sections of the POM, plus an extra <<properties>>
- section.
+ 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 of the POM, 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
@@ -279,28 +319,53 @@
<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>
+---+
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,
- and it has an activation section that will trigger its inclusion when the
- system properties contain "env=dev". So, executing:
+ 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 profile named <<<appserverConfig-dev>>> and "env=dev-2" for
+ profile named <<<appserverConfig-dev-2>>>. So, executing:
+
++---+
+mvn -Denv=dev-2 integration-test
++---+
+
+ Would result to a successful build, applying the properties given
+ by profile named <<<appserverConfig-dev-2>>>. And when we execute
+---+
mvn -Denv=dev integration-test
+---+
- should result in a successful build. However, this won't:
+ should result in a successful build. However, executing:
+---+
mvn -Denv=production integration-test
+---+
- Why? Because, the resulting non-interpolated literal value of $\{appserver.home\}
+ Wont 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, along with "test" and possibly even
+ 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
@@ -314,7 +379,89 @@
suppose this <could> act as useful training for the newbie, it's 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.
+
+* How can I tell which profiles are in effect during a build?
+
+ Determining active profiles will help the user to know what particular
+ profiles has been executed during a build. We can use the <<maven-help-plugin>>
+ to tell what profiles are in effect during a build.
+
++---+
+ mvn help:active-profiles
++---+
+
+ Let us have some small samples that will help us to understand more on the
+ <active-profiles> goal of the plugin.
+
+ From the last example of profile in the pom.xml, you'll notice that there are
+ two profiles named <<<appserverConfig-dev>>> and <<<appserverConfig-dev-2>>>
+ which has different value of properties to be given. If we are going
+ to execute:
+
++---+
+ mvn help:active-profiles -Denv=dev
++---+
+
+ The result will give a bulleted list of the id of the profile with an
+ activation property of "env=dev" together with the source where it was
+ declared. See sample below
+
++---+
+The following profiles are active:
+
+ - appserverConfig-dev (source: pom)
++---+
+
+ Now if we have a profile declared in settings.xml(refer to the sample of profile
+ in settings.xml) and been set to be an active profile and execute
+
++---+
+ mvn help:active-profiles
++---+
+
+ The result should be something like this
+
++---+
+The following profiles are active:
+
+ - appserverConfig (source: settings.xml)
++---+
+
+ Even we dont have an activation property, a profile has been listed as active.
+ Why? Like we mentioned before, profile that has been set as an active profile
+ in the settings.xml is automatically activated.
+
+ Now if we have somthing like a profile in the settings.xml that has been set
+ as an active profile and triggered a profile in the pom. Which profile do
+ you think will have an effect on the build?
+
++---+
+ mvn help:active-profiles -P appserverConfig-dev
++---+
+ This will list the activated profiles
+
++---+
+The following profiles are active:
+
+ - appserverConfig-dev (source: pom)
+ - appserverConfig (source: settings.xml)
++---+
+
+ Even though it listed the two of the active profiles, we are not sure which
+ of them has been applied. To see the effect on build execute
+
++---+
+ mvn help:effective-pom -P appserverConfig-dev
++---+
+
+ This will print the effective POM for this build configuration out to the
+ console. Take note that profiles in the settings.xml takes higher priority
+ than profiles in the pom. So the profile that has been applied here is
+ <<<appserverConfig>>> not <<<appserverConfig-dev>>>.
+
+ If you want to redirect it to a file called <<<effective-pom.xml>>>,
+ use the command-line option <<<-Doutput=effective-pom.xml>>>.
* Naming Conventions
@@ -339,30 +486,5 @@
The right command-line option can be had by simply substituting "=" for "-" in
the profile id.
-
-* Getting Help
-
- If you get lost when working with a profile-enabled build, you can get a glance
- into the build-time POM and active profiles using the <<maven-projecthelp-plugin>>.
-
- To see the list of active profiles, issue:
-
-+---+
-mvn projecthelp:active-profiles -Denv=test
-+---+
-
- This should render a bulleted list of the profiles (hopefully including one
- named <<env-test>> for this build).
-
- If you want to see the effect that the current active profiles have had on the
- POM, issue:
-
-+---+
-mvn projecthelp:effective-pom -Denv=test
-+---+
-
- This will print the effective POM for this build configuration out to the
- console. If you want to redirect it to a file called <<<effective-pom.xml>>>,
- use the command-line option <<<-Doutput=effective-pom.xml>>>.