[maven-site] branch master updated: [MNGSITE-502] Document profile activation based on packaging (#379)

[kw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 7333a35f [MNGSITE-502] Document profile activation based on packaging (#379)
7333a35f is described below

commit 7333a35f68e14b0f8775bb2b1a8c5555de801202
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Feb 6 17:35:47 2023 +0100

    [MNGSITE-502] Document profile activation based on packaging (#379)
    
    Improve structure within profile activation documentation
---
 .../introduction/introduction-to-profiles.apt      | 53 ++++++++++++++++++----
 content/apt/pom.apt.vm                             |  4 +-
 2 files changed, 46 insertions(+), 11 deletions(-)

diff --git a/content/apt/guides/introduction/introduction-to-profiles.apt b/content/apt/guides/introduction/introduction-to-profiles.apt
index 2fce2774..0208564b 100644
--- a/content/apt/guides/introduction/introduction-to-profiles.apt
+++ b/content/apt/guides/introduction/introduction-to-profiles.apt
@@ -28,7 +28,7 @@
 
 Introduction to Build Profiles
 
-%{toc|section=0|fromDepth=2|toDepth=3}
+%{toc|section=0|fromDepth=2|toDepth=5}
 
   Apache Maven goes to great lengths to ensure that builds are portable. Among
   other things, this means allowing build configuration inside the POM,
@@ -84,18 +84,24 @@ Introduction to Build Profiles
 
   A profile can be activated in several ways:
 
-  * From the command line
+  * Explicitly
 
-  * Through Maven settings
-
-  * Based on environment variables
-
-  * OS settings
+  * Implicitly
+  
+  ** Based on OS
+  
+  ** Based on system properties
+  
+  ** Based on presence of files
+  
+  []
 
-  * Present or missing files
+  Refer to the sections below for details.
 
 ** Details on profile activation
 
+*** Explicit profile activation
+
   Profiles can be explicitly specified using the <<<-P>>> command line flag.
 
   This flag is followed by a comma-delimited list of
@@ -126,12 +132,16 @@ mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3
   Profiles listed in the <<<\<activeProfiles\>>>> tag would be activated by default
   every time a project use it.
 
+*** Implicit profile activation
+
   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
   JDK version matching, operating system matching or
   the presence/the value of a system property. Here are some examples.
 
+**** JDK
+
   The following configuration will trigger the profile when the JDK's
   version <starts with> "1.4" (eg. "1.4.0_08", "1.4.2_07", "1.4"), in particular it <won't be active>
   for <<newer>> versions like "1.8" or "11":
@@ -164,7 +174,10 @@ mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3
 
   <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.
 
-  This next one will activate based on OS settings. See the {{{/enforcer/enforcer-rules/requireOS.html}Maven Enforcer Plugin}} for more details about OS values.
+
+**** OS
+
+  This next one will activate based on the detected operating system. See the {{{/enforcer/enforcer-rules/requireOS.html}Maven Enforcer Plugin}} for more details about OS values.
 
 +---+
 <profiles>
@@ -182,6 +195,8 @@ mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3
 </profiles>
 +---+
 
+**** Property
+
   The profile below will be activated when the system property "debug" is specified
   with any value:
 
@@ -267,6 +282,26 @@ mvn groupId:artifactId:goal -Denvironment=test
   <<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.
 
+  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:
+  
++---+
+<profiles>
+  <profile>
+    <activation>
+      <property>
+        <name>packaging</name>
+        <value>war</value>
+      </property>
+    </activation>
+    ...
+  </profile>
+</profiles>
++---+
+
+**** Files
+
   This example will trigger the profile when the generated file
   <<<target/generated-sources/axistools/wsdl2java/org/apache/maven>>> is missing.
 
diff --git a/content/apt/pom.apt.vm b/content/apt/pom.apt.vm
index 7b9f1114..a76ee4e3 100644
--- a/content/apt/pom.apt.vm
+++ b/content/apt/pom.apt.vm
@@ -1981,8 +1981,8 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
   The <<<os>>> element can define some operating system specific properties shown above. See the maven-enforcer-plugins {{{https://maven.apache.org/enforcer/enforcer-rules/requireOS.html}RequireOS Rule}} for more details about OS values.
 
   * <<property>>:
-  The <<<profile>>> will activate if Maven detects a system property and commandline property (a value which can be dereferenced within the POM by <<<$\{name\}>>>)
-  of the corresponding <<<name=value>>> pair.
+  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