You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2023/02/06 15:35:55 UTC
[maven-site] branch feature/document-packaging-based-profile-activation created (now c18bb8db)
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a change to branch feature/document-packaging-based-profile-activation
in repository https://gitbox.apache.org/repos/asf/maven-site.git
at c18bb8db [MNGSITE-502] Document profile activation based on packaging
This branch includes the following new commits:
new c18bb8db [MNGSITE-502] Document profile activation based on packaging
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-site] 01/01: [MNGSITE-502] Document profile activation based on packaging
Posted by kw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/document-packaging-based-profile-activation
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit c18bb8dbff7be8d8d96a2e9acb4c8a6540e49035
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Feb 6 16:35:27 2023 +0100
[MNGSITE-502] Document profile activation based on packaging
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