Modified: maven/website/content/guides/introduction/introduction-to-profiles.html ============================================================================== --- maven/website/content/guides/introduction/introduction-to-profiles.html (original) +++ maven/website/content/guides/introduction/introduction-to-profiles.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/introduction/introduction-to-profiles.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/introduction/introduction-to-profiles.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="John Casey/Allan Ramirez" /> <meta name="date" content="2008-01-01" /> - <title>Maven</title> + <title>Maven â Introduction to build profiles</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-profiles.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Introduction to build profiles <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-profiles.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -154,7 +151,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Introduction_to_Build_Profiles"></a> +<section> <h1>Introduction to Build Profiles</h1> <ul> <li><a href="#What_are_the_different_types_of_profile.3F_Where_is_each_defined.3F">What are the different types of profile? Where is each defined?</a></li> @@ -186,7 +183,7 @@ <li><a href="#Naming_Conventions">Naming Conventions</a></li></ul> <p>Apache Maven goes to great lengths to ensure that builds are portable. Among other things, this means allowing build configuration inside the POM, avoiding <b>all</b> filesystem references (in inheritance, dependencies, and other places), and leaning much more heavily on the local repository to store the metadata needed to make this possible.</p> <p>However, sometimes portability is not entirely possible. Under certain conditions, plugins may need to be configured with local filesystem paths. Under other circumstances, a slightly different dependency set will be required, and the project's artifact name may need to be adjusted slightly. And at still other times, you may even need to include a whole plugin in the build lifecycle depending on the detected build environment.</p> -<p>To address these circumstances, Maven supports build profiles. Profiles are specified using a subset of the elements available in the POM itself (plus one extra section), and are triggered in any of a variety of ways. They modify the POM at build time, and are meant to be used in complementary sets to give equivalent-but-different parameters for a set of target environments (providing, for example, the path of the appserver root 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. This will also minimize the use of <code>-f</code> 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 running with one POM only.</p><section><a id="What_are_the_different_types_of_profile.3F_Where_is_each_defined. 3F"></a> +<p>To address these circumstances, Maven supports build profiles. Profiles are specified using a subset of the elements available in the POM itself (plus one extra section), and are triggered in any of a variety of ways. They modify the POM at build time, and are meant to be used in complementary sets to give equivalent-but-different parameters for a set of target environments (providing, for example, the path of the appserver root 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. This will also minimize the use of <code>-f</code> 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 running with one POM only.</p><section> <h2>What are the different types of profile? Where is each defined?</h2> <ul> <li>Per Project @@ -196,9 +193,9 @@ <li>Global <p>- Defined in the <a href="/ref/current/maven-settings/settings.html"> global Maven-settings</a> <code>(${maven.home}/conf/settings.xml)</code>.</p></li> <li>Profile descriptor -<p>- a descriptor located in <a href="/ref/2.2.1/maven-profile/profiles.html">project basedir <code>(profiles.xml)</code></a> (no longer supported in Maven 3.0 and above; see <a class="externalLink" href="https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes#Maven3.xCompatibilityNotes-profiles.xml";> Maven 3 compatibility notes</a>)</p></li></ul></section><section><a id="Profile_Inheritance"></a> +<p>- a descriptor located in <a href="/ref/2.2.1/maven-profile/profiles.html">project basedir <code>(profiles.xml)</code></a> (no longer supported in Maven 3.0 and above; see <a class="externalLink" href="https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes#Maven3.xCompatibilityNotes-profiles.xml";> Maven 3 compatibility notes</a>)</p></li></ul></section><section> <h2>Profile Inheritance</h2> -<p>The profiles are not inherited as other POM elements by child POMs. Instead they are resolved very early by the <a href="/ref/current/maven-model-builder/">Maven Model Builder</a> and only the effects of active profiles are inherited (e.g. the plugins defined in the profile). That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile (even if it has the same id).</p></section><section><a id="How_can_a_profile_be_triggered.3F_How_does_this_vary_according_to_the_type_of_profile_being_used.3F"></a> +<p>The profiles are not inherited as other POM elements by child POMs. Instead they are resolved very early by the <a href="/ref/current/maven-model-builder/">Maven Model Builder</a> and only the effects of active profiles are inherited (e.g. the plugins defined in the profile). That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile (even if it has the same id).</p></section><section> <h2>How can a profile be triggered? How does this vary according to the type of profile being used?</h2> <p>A profile can be activated in several ways:</p> <ul> @@ -208,23 +205,24 @@ <li>Based on OS</li> <li>Based on system properties</li> <li>Based on presence of files</li></ul></li></ul> -<p>Refer to the sections below for details.</p><section><a id="Details_on_profile_activation"></a> -<h3>Details on profile activation</h3><section><a id="Explicit_profile_activation"></a> +<p>Refer to the sections below for details.</p><section> +<h3>Details on profile activation</h3><section> <h4>Explicit profile activation</h4> <p>Profiles can be explicitly specified using the <code>-P</code> command line flag.</p> <p>This flag is followed by a comma-delimited list of profile IDs to use. The profile(s) specified in the option are activated in addition to any profiles which are activated by their activation configuration or the <code><activeProfiles></code> section in <code>settings.xml</code>. From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved. To prevent this, prefix the profile identifier with an <code>?</code>, marking it as optional:</p> -<pre>mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3</pre> +<div class="verbatim"> +<pre>mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3</pre></div> <p>Profiles can be activated in the Maven settings, via the <code><activeProfiles></code> section. This section takes a list of <code><activeProfile></code> elements, each containing a profile-id inside.</p> -<pre><code><settings> +<div class="verbatim source"><pre class="prettyprint linenums"><settings> ... <activeProfiles> <activeProfile>profile-1</activeProfile> </activeProfiles> ... -</settings></code></pre> +</settings></pre></div> <p>Profiles listed in the <code><activeProfiles></code> tag would be activated by default every time a project use it.</p> <p>Profiles can also be active by default using a configuration like the following in a POM:</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <id>profile-1</id> <activation> @@ -232,33 +230,33 @@ </activation> ... </profile> -</profiles></code></pre> -<p>This profile will automatically be active for all builds unless another profile in the same POM is activated using one of the previously described methods. All profiles that are active by default are automatically deactivated when a profile in the POM is activated on the command line or through its activation config.</p></section><section><a id="Implicit_profile_activation"></a> +</profiles></pre></div> +<p>This profile will automatically be active for all builds unless another profile in the same POM is activated using one of the previously described methods. All profiles that are active by default are automatically deactivated when a profile in the POM is activated on the command line or through its activation config.</p></section><section> <h4>Implicit profile activation</h4> -<p>Profiles can be automatically triggered based on the detected state of the build environment. These triggers are specified via an <code><activation></code> 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. The implicit profile activation always only refers to the container profile (and not to profiles in other modules with the same id). Here are some examples.</p><section><a id="JDK"></a> +<p>Profiles can be automatically triggered based on the detected state of the build environment. These triggers are specified via an <code><activation></code> 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. The implicit profile activation always only refers to the container profile (and not to profiles in other modules with the same id). Here are some examples.</p><section> <h5>JDK</h5> <p>The following configuration will trigger the profile when the JDK's version <i>starts with</i> "1.4" (eg. "1.4.0_08", "1.4.2_07", "1.4"), in particular it <i>won't be active</i> for <b>newer</b> versions like "1.8" or "11":</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <jdk>1.4</jdk> </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p><a href="/enforcer/enforcer-rules/versionRanges.html"> Ranges</a> can also be used. Range values must start with either <code>[</code> or <code>(</code>. Otherwise, the value is interpreted as a prefix. The following honours versions 1.3, 1.4 and 1.5.</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <jdk>[1.3,1.6)</jdk> </activation> ... </profile> -</profiles></code></pre> -<p><i>Note:</i> an upper bound such as <code>,1.5]</code> is likely not to include most releases of 1.5, since they will have an additional "patch" release such as <code>_05</code> that is not taken into consideration in the above range.</p></section><section><a id="OS"></a> +</profiles></pre></div> +<p><i>Note:</i> an upper bound such as <code>,1.5]</code> is likely not to include most releases of 1.5, since they will have an additional "patch" release such as <code>_05</code> that is not taken into consideration in the above range.</p></section><section> <h5>OS</h5> <p>This next one will activate based on the detected operating system. See the <a href="/enforcer/enforcer-rules/requireOS.html">Maven Enforcer Plugin</a> for more details about OS values.</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <os> @@ -270,14 +268,14 @@ </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p>The values are interpreted as Strings and are matched against the <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html";>Java System properties</a> <code>os.name</code>, <code>os.arch</code>, <code>os.version</code> and the family being derived from those.</p> <p>Each value can be prefixed with <code>!</code> to negate the matching. The values match if they are (not) equal to the actual String value. All given OS conditions must match for the profile to be considered for activation.</p> <p>Since <a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-5726";>Maven 3.9.7</a> the value for <code>version</code> may be prefixed with <code>regex:</code>. In that case <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/essential/regex/";>regular pattern matching</a> is applied for the version matching.</p> -<p>The actual OS values which need to match the given values are emitted when executing <code>mvn --version</code>.</p></section><section><a id="Property"></a> +<p>The actual OS values which need to match the given values are emitted when executing <code>mvn --version</code>.</p></section><section> <h5>Property</h5> <p>The profile below will be activated when the system property "debug" is specified with any value:</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <property> @@ -286,9 +284,9 @@ </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p>The following profile will be activated when the system property "debug" is not defined at all:</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <property> @@ -297,9 +295,9 @@ </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p>The following profile will be activated when the system property "debug" is not defined, or is defined with a value which is not "true".</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <property> @@ -309,12 +307,13 @@ </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p>To activate this you would type one of those on the command line:</p> +<div class="verbatim"> <pre>mvn groupId:artifactId:goal -mvn groupId:artifactId:goal -Ddebug=false</pre> +mvn groupId:artifactId:goal -Ddebug=false</pre></div> <p>The next example will trigger the profile when the system property "environment" is specified with the value "test":</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <property> @@ -324,13 +323,14 @@ mvn groupId:artifactId:goal -Ddebug=fals </activation> ... </profile> -</profiles></code></pre> +</profiles></pre></div> <p>To activate this you would type this on the command line:</p> -<pre>mvn groupId:artifactId:goal -Denvironment=test</pre> +<div class="verbatim"> +<pre>mvn groupId:artifactId:goal -Denvironment=test</pre></div> <p>As of Maven 3.0, profiles in the POM can also be activated based on properties from active profiles from the <code>settings.xml</code>.</p> <p><b>Note</b>: Environment variables like <code>FOO</code> are available as properties of the form <code>env.FOO</code>. Further note that environment variable names are normalized to all upper-case on Windows.</p> <p>Since Maven 3.9.0 one can also evaluate the POM's packaging value by referencing property <code>packaging</code>. 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 <code>war</code> is built:</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <property> @@ -340,10 +340,10 @@ mvn groupId:artifactId:goal -Ddebug=fals </activation> ... </profile> -</profiles></code></pre></section><section><a id="Files"></a> +</profiles></pre></div></section><section> <h5>Files</h5> <p>This example will trigger the profile when the generated file <code>target/generated-sources/axistools/wsdl2java/org/apache/maven</code> is missing.</p> -<pre><code><profiles> +<div class="verbatim source"><pre class="prettyprint linenums"><profiles> <profile> <activation> <file> @@ -352,23 +352,25 @@ mvn groupId:artifactId:goal -Ddebug=fals </activation> ... </profile> -</profiles></code></pre> -<p>The tags <code><exists></code> and <code><missing></code> can be interpolated. Supported variables are system properties like <code>${user.home}</code> and environment variables like <code>${env.HOME}</code>. Please note that properties and values defined in the POM itself are not available for interpolation here, e.g. the above example activator cannot use <code>${project.build.directory}</code> but needs to hard-code the path <code>target</code>.</p></section></section><section><a id="Multiple_conditions"></a> +</profiles></pre></div> +<p>The tags <code><exists></code> and <code><missing></code> can be interpolated. Supported variables are system properties like <code>${user.home}</code> and environment variables like <code>${env.HOME}</code>. Please note that properties and values defined in the POM itself are not available for interpolation here, e.g. the above example activator cannot use <code>${project.build.directory}</code> but needs to hard-code the path <code>target</code>.</p></section></section><section> <h4>Multiple conditions</h4> -<p>Different implicit activation types can be combined in one profile. The profile is then only active if all conditions are met (since Maven 3.2.2, <a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-4565";>MNG-4565</a>). Using the same type more than once in the same profile is not supported (<a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-5909";>MNG-5909</a>, <a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-3328";>MNG-3328</a>).</p></section></section><section><a id="Deactivating_a_profile"></a> +<p>Different implicit activation types can be combined in one profile. The profile is then only active if all conditions are met (since Maven 3.2.2, <a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-4565";>MNG-4565</a>). Using the same type more than once in the same profile is not supported (<a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-5909";>MNG-5909</a>, <a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-3328";>MNG-3328</a>).</p></section></section><section> <h3>Deactivating a profile</h3> <p>One or more profiles can be deactivated using the command line by prefixing their identifier with either the character '!' or '-' as shown below.</p> <p><b>Note</b> that <code>!</code> needs to be escaped with <code>\</code> or quoted in Bash, ZSH and other shells as it has <a class="externalLink" href="https://www.gnu.org/software/bash/manual/html_node/Event-Designators.html";>a special meaning</a>. Also there is a known bug with command line option values starting with <code>-</code> (<a class="externalLink" href="https://issues.apache.org/jira/browse/CLI-309";>CLI-309</a>), therefore it is recommended to use it with the syntax <code>-P=-profilename</code>.</p> -<pre>mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3</pre> +<div class="verbatim"> +<pre>mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3</pre></div> <p>or</p> -<pre>mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3</pre> -<p>This can be used to deactivate profiles marked as activeByDefault or profiles that would otherwise be activated through their activation config.</p></section></section><section><a id="Which_areas_of_a_POM_can_be_customized_by_each_type_of_profile.3F_Why.3F"></a> +<div class="verbatim"> +<pre>mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3</pre></div> +<p>This can be used to deactivate profiles marked as activeByDefault or profiles that would otherwise be activated through their activation config.</p></section></section><section> <h2>Which areas of a POM can be customized by each type of profile? Why?</h2> <p>Now that we've talked about where to specify profiles, and how to activate them, it will be useful to talk about <i>what</i> you can specify in a profile. As with the other aspects of profile configuration, this answer is not straightforward.</p> -<p>Depending on where you choose to configure your profile, you will have access to varying POM configuration options.</p><section><a id="Profiles_in_external_files"></a> +<p>Depending on where you choose to configure your profile, you will have access to varying POM configuration options.</p><section> <h3>Profiles in external files</h3> <p>Profiles specified in external files (i.e in <code>settings.xml</code> or <code>profiles.xml</code>) 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 <code><repositories></code> and <code><pluginRepositories></code> sections, plus an extra <code><properties></code> section.</p> -<p>The <code><properties></code> 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 <code>${profile.provided.path}</code>.</p></section><section><a id="Profiles_in_POMs"></a> +<p>The <code><properties></code> 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 <code>${profile.provided.path}</code>.</p></section><section> <h3>Profiles in POMs</h3> <p>On the other hand, if your profiles can be reasonably specified <i>inside</i> the POM, you have many more options. The trade-off, of course, is that you can only modify <i>that</i> 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.</p> <p>Profiles specified in the POM can modify <a href="/ref/current/maven-model/maven.html">the following POM elements</a>:</p> @@ -392,14 +394,14 @@ mvn groupId:artifactId:goal -Ddebug=fals <li><code><finalName></code></li> <li><code><filters></code></li> <li><code><pluginManagement></code></li> -<li><code><plugins></code></li></ul></li></ul></section><section><a id="POM_elements_outside_.3Cprofiles.3E"></a> +<li><code><plugins></code></li></ul></li></ul></section><section> <h3>POM elements outside <profiles></h3> <p>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.</p> -<p>External files such as <code>settings.xml</code> and <code>profiles.xml</code> 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 <code>settings.xml</code> 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 <code>settings.xml</code> 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.</p></section></section><section><a id="Profile_Order"></a> +<p>External files such as <code>settings.xml</code> and <code>profiles.xml</code> 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 <code>settings.xml</code> 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 <code>settings.xml</code> 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.</p></section></section><section> <h2>Profile Order</h2> <p>All profile elements in a POM from active profiles overwrite the global elements with the same name of the POM or extend those in case of collections. In case multiple profiles are active in the same POM or external file, the ones which are defined <b>later</b> take precedence over the ones defined <b>earlier</b> (independent of their profile id and activation order).</p> <p>Example:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <repositories> <repository> @@ -436,14 +438,14 @@ mvn groupId:artifactId:goal -Ddebug=fals ... </profiles> ... -</project></code></pre> -<p>This leads to the repository list: <code>profile-2-repo, profile-1-repo, global-repo</code>.</p></section><section><a id="Profile_Pitfalls"></a> +</project></pre></div> +<p>This leads to the repository list: <code>profile-2-repo, profile-1-repo, global-repo</code>.</p></section><section> <h2>Profile Pitfalls</h2> <p>We've already mentioned the fact that adding profiles to your build has the potential to break portability for your project. We've even gone so far as to highlight circumstances where profiles are likely to break project portability. However, it's worth reiterating those points as part of a more coherent discussion about some pitfalls to avoid when using profiles.</p> -<p>There are two main problem areas to keep in mind when using profiles. First are external properties, usually used in plugin configurations. These pose the risk of breaking portability in your project. The other, more subtle area is the incomplete specification of a natural set of profiles.</p><section><a id="External_Properties"></a> +<p>There are two main problem areas to keep in mind when using profiles. First are external properties, usually used in plugin configurations. These pose the risk of breaking portability in your project. The other, more subtle area is the incomplete specification of a natural set of profiles.</p><section> <h3>External Properties</h3> <p>External property definition concerns any property value defined outside the <code>pom.xml</code> 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 <code>settings.xml</code> may cause your integration test plugin to fail when another user on the team attempts to build without a similar <code>settings.xml</code>. Consider the following <code>pom.xml</code> snippet for a web application project:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -459,9 +461,9 @@ mvn groupId:artifactId:goal -Ddebug=fals </plugins> </build> ... -</project></code></pre> +</project></pre></div> <p>Now, in your local <code>${user.home}/.m2/settings.xml</code>, you have:</p> -<pre><code><settings> +<div class="verbatim source"><pre class="prettyprint linenums"><settings> ... <profiles> <profile> @@ -476,14 +478,14 @@ mvn groupId:artifactId:goal -Ddebug=fals <activeProfile>appserverConfig</activeProfile> </activeProfiles> ... -</settings></code></pre> +</settings></pre></div> <p>When you build the <b>integration-test</b> lifecycle phase, your integration tests pass, since the path you've provided allows the test plugin to install and test this web application.</p> <p><i>However</i>, when your colleague attempts to build to <b>integration-test</b>, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter <code><appserverHome></code>, or worse, that the value of that parameter - literally <code>${appserver.home}</code> - is invalid (if it warns you at all).</p> <p>Congratulations, your project is now non-portable. Inlining this profile in your <code>pom.xml</code> 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 <code><pluginManagement></code> section of a team-level POM or similar, and simply inherit the paths.</p> -<p>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.</p></section><section><a id="Incomplete_Specification_of_a_Natural_Profile_Set"></a> +<p>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.</p></section><section> <h3>Incomplete Specification of a Natural Profile Set</h3> <p>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 <code>pom.xml</code> snippet from above one more time:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -499,9 +501,9 @@ mvn groupId:artifactId:goal -Ddebug=fals </plugins> </build> ... -</project></code></pre> +</project></pre></div> <p>Now, consider the following profile, which would be specified inline in the <code>pom.xml</code>:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> ... <profiles> <profile> @@ -531,47 +533,59 @@ mvn groupId:artifactId:goal -Ddebug=fals </profile> </profiles> .. -</project></code></pre> +</project></pre></div> <p>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 <code>appserverConfig-dev-2</code> is added and it has an activation section that will trigger its inclusion when the system properties contain "env=dev" for a profile named <code>appserverConfig-dev</code> and "env=dev-2" for a profile named <code>appserverConfig-dev-2</code>. So, executing:</p> -<pre>mvn -Denv=dev-2 integration-test</pre> +<div class="verbatim"> +<pre>mvn -Denv=dev-2 integration-test</pre></div> <p>will result in a successful build, applying the properties given by profile named <code>appserverConfig-dev-2</code>. And when we execute</p> -<pre>mvn -Denv=dev integration-test</pre> +<div class="verbatim"> +<pre>mvn -Denv=dev integration-test</pre></div> <p>it will result in a successful build applying the properties given by the profile named <code>appserverConfig-dev</code>. However, executing:</p> -<pre>mvn -Denv=production integration-test</pre> +<div class="verbatim"> +<pre>mvn -Denv=production integration-test</pre></div> <p>will not do a successful build. Why? Because, the resulting non-interpolated literal value of <code>${appserver.home}</code> 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.</p> -<p>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 <i>could</i> 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 <i>whole</i> set of profiles.</p></section></section><section><a id="How_can_I_tell_which_profiles_are_in_effect_during_a_build.3F"></a> +<p>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 <i>could</i> 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 <i>whole</i> set of profiles.</p></section></section><section> <h2>How can I tell which profiles are in effect during a build?</h2> <p>Determining active profiles will help the user to know what particular profiles has been executed during a build. We can use the <a href="/plugins/maven-help-plugin/">Maven Help Plugin</a> to tell what profiles are in effect during a build.</p> -<pre> mvn help:active-profiles</pre> +<div class="verbatim"> +<pre> mvn help:active-profiles</pre></div> <p>Let us have some small samples that will help us to understand more on the <i>active-profiles</i> goal of that plugin.</p> <p>From the last example of profiles in the <code>pom.xml</code>, you'll notice that there are two profiles named <code>appserverConfig-dev</code> and <code>appserverConfig-dev-2</code> which has been given different values for properties. If we go ahead and execute:</p> -<pre> mvn help:active-profiles -Denv=dev</pre> +<div class="verbatim"> +<pre> mvn help:active-profiles -Denv=dev</pre></div> <p>The result will be 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.</p> +<div class="verbatim"> <pre>The following profiles are active: - - appserverConfig-dev (source: pom)</pre> + - appserverConfig-dev (source: pom)</pre></div> <p>Now if we have a profile declared in <code>settings.xml</code> (refer to the sample of profile in <code>settings.xml</code>) and that have been set to be an active profile and execute:</p> -<pre> mvn help:active-profiles</pre> +<div class="verbatim"> +<pre> mvn help:active-profiles</pre></div> <p>The result should be something like this</p> +<div class="verbatim"> <pre>The following profiles are active: - - appserverConfig (source: settings.xml)</pre> + - appserverConfig (source: settings.xml)</pre></div> <p>Even though we don't have an activation property, a profile has been listed as active. Why? Like we mentioned before, a profile that has been set as an active profile in the <code>settings.xml</code> is automatically activated.</p> <p>Now if we have something like a profile in the <code>settings.xml</code> that has been set as an active profile and also triggered a profile in the POM. Which profile do you think will have an effect on the build?</p> -<pre> mvn help:active-profiles -P appserverConfig-dev</pre> +<div class="verbatim"> +<pre> mvn help:active-profiles -P appserverConfig-dev</pre></div> <p>This will list the activated profiles:</p> +<div class="verbatim"> <pre>The following profiles are active: - appserverConfig-dev (source: pom) - - appserverConfig (source: settings.xml)</pre> + - appserverConfig (source: settings.xml)</pre></div> <p>Even though it listed the two active profiles, we are not sure which one of them has been applied. To see the effect on the build execute:</p> -<pre> mvn help:effective-pom -P appserverConfig-dev</pre> +<div class="verbatim"> +<pre> mvn help:effective-pom -P appserverConfig-dev</pre></div> <p>This will print the effective POM for this build configuration out to the console. Take note that profiles in the <code>settings.xml</code> takes higher priority than profiles in the POM. So the profile that has been applied here is <code>appserverConfig</code> not <code>appserverConfig-dev</code>.</p> -<p>If you want to redirect the output from the plugin to a file called <code>effective-pom.xml</code>, use the command-line option <code>-Doutput=effective-pom.xml</code>.</p></section><section><a id="Naming_Conventions"></a> +<p>If you want to redirect the output from the plugin to a file called <code>effective-pom.xml</code>, use the command-line option <code>-Doutput=effective-pom.xml</code>.</p></section><section> <h2>Naming Conventions</h2> <p>By now you've noticed that profiles are a natural way of addressing the problem of different build configuration requirements for different target environments. Above, we discussed the concept of a "natural set" of profiles to address this situation, and the importance of considering the whole set of profiles that will be required.</p> <p>However, the question of how to organize and manage the evolution of that set is non-trivial as well. Just as a good developer strives to write self-documenting code, it's important that your profile id's give a hint to their intended use. One good way to do this is to use the common system property trigger as part of the name for the profile. This might result in names like <b>env-dev</b>, <b>env-test</b>, and <b>env-prod</b> for profiles that are triggered by the system property <b>env</b>. Such a system leaves a highly intuitive hint on how to activate a build targeted at a particular environment. Thus, to activate a build for the test environment, you need to activate <b>env-test</b> by issuing:</p> -<pre>mvn -Denv=test <phase></pre> +<div class="verbatim"> +<pre>mvn -Denv=test <phase></pre></div> <p>The right command-line option can be had by simply substituting "=" for "-" in the profile id.</p></section></section> </main> </div>
Modified: maven/website/content/guides/introduction/introduction-to-repositories.html ============================================================================== --- maven/website/content/guides/introduction/introduction-to-repositories.html (original) +++ maven/website/content/guides/introduction/introduction-to-repositories.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/introduction/introduction-to-repositories.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/introduction/introduction-to-repositories.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Jason van Zyl" /> <meta name="author" content="Brian Fox" /> <meta name="date" content="2008-05-13" /> - <title>Maven</title> + <title>Maven â Introduction to Repositories</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-repositories.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Introduction to Repositories <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-repositories.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -163,44 +160,45 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Introduction_to_Repositories"></a> -<h1>Introduction to Repositories</h1><section><a id="Artifact_Repositories"></a> +<section> +<h1>Introduction to Repositories</h1><section> <h2>Artifact Repositories</h2> <p>A repository in Maven holds build artifacts and dependencies of varying types.</p> <p>There are exactly two types of repositories: <b>local</b> and <b>remote</b>:</p> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li>the <b>local</b> repository is a directory on the computer where Maven runs. It caches remote downloads and contains temporary build artifacts that you have not yet released.</li> <li><b>remote</b> repositories refer to any other type of repository, accessed by a variety of protocols such as <code>file://</code> and <code>https://</code>. These repositories might be a truly remote repository set up by a third party to provide their artifacts for downloading (for example, <a class="externalLink" href="https://repo.maven.apache.org/maven2/";>repo.maven.apache.org</a>). Other "remote" repositories may be internal repositories set up on a file or HTTP server within your company, used to share private artifacts between development teams and for releases.</li></ol> -<p>Local and remote repositories are structured the same way so that scripts can run on either side, or they can be synced for offline use. The layout of the repositories is completely transparent to the Maven user, however.</p></section><section><a id="Using_Repositories"></a> +<p>Local and remote repositories are structured the same way so that scripts can run on either side, or they can be synced for offline use. The layout of the repositories is completely transparent to the Maven user, however.</p></section><section> <h2>Using Repositories</h2> <p>In general, you should not need to do anything with the local repository on a regular basis, except clean it out if you are short on disk space (or erase it completely if you are willing to download everything again).</p> -<p>For the remote repositories, they are used for both downloading and uploading (if you have the permission to do so).</p><section><a id="Downloading_from_a_Remote_Repository"></a> +<p>For the remote repositories, they are used for both downloading and uploading (if you have the permission to do so).</p><section> <h3>Downloading from a Remote Repository</h3> <p>Downloading in Maven is triggered by a project declaring a dependency that is not present in the local repository (or for a <code>SNAPSHOT</code>, when the remote repository contains one that is newer). By default, Maven will download from the <a class="externalLink" href="https://repo.maven.apache.org/maven2/";>central</a> repository.</p> <p>To override this, you need to specify a <code>mirror</code> as shown in <a href="../mini/guide-mirror-settings.html">Using Mirrors for Repositories</a>.</p> <p>You can set this in your <code>settings.xml</code> file to globally use a certain mirror. However, it is common for a project to <a href="../mini/guide-multiple-repositories.html">customise the repository in its <code>pom.xml</code></a> and that your setting will take precedence. If dependencies are not being found, check that you have not overridden the remote repository.</p> -<p>For more information on dependencies, see <a href="./introduction-to-dependency-mechanism.html">Dependency Mechanism</a>.</p></section><section><a id="Using_Mirrors_for_the_Central_Repository"></a> +<p>For more information on dependencies, see <a href="./introduction-to-dependency-mechanism.html">Dependency Mechanism</a>.</p></section><section> <h3>Using Mirrors for the Central Repository</h3> -<p>There are <a href="/repository/">several official Central repositories</a> geographically distributed. You can make changes to your <code>settings.xml</code> file to use one or more mirrors. Instructions for this can be found in the guide <a href="../mini/guide-mirror-settings.html">Using Mirrors for Repositories</a>.</p></section></section><section><a id="Building_Offline"></a> +<p>There are <a href="/repository/">several official Central repositories</a> geographically distributed. You can make changes to your <code>settings.xml</code> file to use one or more mirrors. Instructions for this can be found in the guide <a href="../mini/guide-mirror-settings.html">Using Mirrors for Repositories</a>.</p></section></section><section> <h2>Building Offline</h2> <p>If you are temporarily disconnected from the internet and you need to build your projects offline, you can use the offline switch on the CLI:</p> -<pre> mvn -o package</pre> -<p>Many plugins honor the offline setting and do not perform any operations that connect to the internet. Some examples are resolving Javadoc links and link checking the site.</p></section><section><a id="Uploading_to_a_Remote_Repository"></a> +<div class="verbatim"> +<pre> mvn -o package</pre></div> +<p>Many plugins honor the offline setting and do not perform any operations that connect to the internet. Some examples are resolving Javadoc links and link checking the site.</p></section><section> <h2>Uploading to a Remote Repository</h2> -<p>While this is possible for any type of remote repository, you must have the permission to do so. To have someone upload to the Central Maven repository, see <a href="../../repository/index.html">Repository Center</a>.</p></section><section><a id="Internal_Repositories"></a> +<p>While this is possible for any type of remote repository, you must have the permission to do so. To have someone upload to the Central Maven repository, see <a href="../../repository/index.html">Repository Center</a>.</p></section><section> <h2>Internal Repositories</h2> <p>When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an internal repository to house a copy of artifacts, and to publish private artifacts to.</p> <p>Such an internal repository can be downloaded using HTTP or the file system (with a <code>file://</code> URL), and uploaded to using SCP, FTP, or a file copy.</p> <p>As far as Maven is concerned, there is nothing special about this repository: it is another <b>remote repository</b> that contains artifacts to download to a user's local cache, and is a publish destination for artifact releases.</p> -<p>Additionally, you may want to share the repository server with your generated project sites. For more information on creating and deploying sites, see <a href="../mini/guide-site.html">Creating a Site</a>.</p></section><section><a id="Setting_up_the_Internal_Repository"></a> +<p>Additionally, you may want to share the repository server with your generated project sites. For more information on creating and deploying sites, see <a href="../mini/guide-site.html">Creating a Site</a>.</p></section><section> <h2>Setting up the Internal Repository</h2> <p>To set up an internal repository just requires that you have a place to put it, and then copy required artifacts there using the same layout as in a remote repository such as <a class="externalLink" href="https://repo.maven.apache.org/maven2/";>repo.maven.apache.org</a>.</p> <p>It is <i>not</i> recommended that you scrape or <code>rsync://</code> a full copy of central as there is a large amount of data there and doing so will get you banned. You can use a program such as those described on the <a href="../../repository-management.html">Repository Management</a> page to run your internal repository's server, download from the internet as required, and then hold the artifacts in your internal repository for faster downloading later.</p> <p>The other options available are to manually download and vet releases, then copy them to the internal repository, or to have Maven download them for a user, and manually upload the vetted artifacts to the internal repository which is used for releases. This step is the only one available for artifacts where the license forbids their distribution automatically, such as several J2EE JARs provided by Sun. Refer to the <a href="../mini/guide-coping-with-sun-jars.html">Guide to coping with SUN JARs</a> document for more information.</p> -<p>It should be noted that Maven intends to include enhanced support for such features in the future, including click through licenses on downloading, and verification of signatures.</p></section><section><a id="Using_the_Internal_Repository"></a> +<p>It should be noted that Maven intends to include enhanced support for such features in the future, including click through licenses on downloading, and verification of signatures.</p></section><section> <h2>Using the Internal Repository</h2> <p>Using the internal repository is quite simple. Simply make a change to add a <code>repositories</code> element:</p> -<pre><code> +<div class="verbatim source"><pre class="prettyprint linenums"> <project> ... <repositories> @@ -211,8 +209,8 @@ </repositories> ... </project> -</code></pre> -<p>If your internal repository requires authentication, the <code>id</code> element can be used in your <a href="../../settings.html#Servers">settings</a> file to specify login information.</p></section><section><a id="Deploying_to_the_Internal_Repository"></a> +</pre></div> +<p>If your internal repository requires authentication, the <code>id</code> element can be used in your <a href="../../settings.html#Servers">settings</a> file to specify login information.</p></section><section> <h2>Deploying to the Internal Repository</h2> <p>One of the most important reasons to have one or more internal repositories is to be able to publish your own private releases.</p> <p>To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, WebDAV, or the filesystem. Connectivity is accomplished with the various <a href="/wagon/wagon-providers/index.html">wagons</a>. Some wagons may need to be added as <a href="/ref/current/maven-model/maven.html#class_extension">extension</a> to your build.</p></section></section> Modified: maven/website/content/guides/introduction/introduction-to-the-lifecycle.html ============================================================================== --- maven/website/content/guides/introduction/introduction-to-the-lifecycle.html (original) +++ maven/website/content/guides/introduction/introduction-to-the-lifecycle.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/guides/introduction/introduction-to-the-lifecycle.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/guides/introduction/introduction-to-the-lifecycle.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="date" content="2006-06-16 2015-04-04" /> - <title>Maven</title> + <title>Maven â Introduction to the Build Lifecycle</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-the-lifecycle.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Introduction to the Build Lifecycle <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-the-lifecycle.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -155,8 +152,8 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Introduction_to_the_Build_Lifecycle"></a> -<h1>Introduction to the Build Lifecycle</h1><section><a id="Table_Of_Contents"></a> +<section> +<h1>Introduction to the Build Lifecycle</h1><section> <h2>Table Of Contents</h2> <ul> <li><a href="#Build_Lifecycle_Basics">Build Lifecycle Basics</a></li> @@ -186,16 +183,19 @@ <h3><a id="Usual_Command_Line_Calls">Usual Command Line Calls</a></h3> <p>You should select the phase that matches your outcome. If you want your jar, run <code>package</code>. If you want to run the unit tests, run <code>test</code>.</p> <p>If you are uncertain what you want, the preferred phase to call is</p> -<pre>mvn verify</pre> +<div class="verbatim"> +<pre>mvn verify</pre></div> <p>This command executes each default lifecycle phase in order (<code>validate</code>, <code>compile</code>, <code>package</code>, etc.), before executing <code>verify</code>. You only need to call the last build phase to be executed, in this case, <code>verify</code>. In most cases the effect is the same as <code>package</code>. However, in case there are integration-tests, these will be executed as well. And during the <code>verify</code> phase some additional checks can be done, e.g. if your code written according to the predefined checkstyle rules.</p> <p>In a build environment, use the following call to cleanly build and deploy artifacts into the shared repository.</p> -<pre>mvn clean deploy</pre> +<div class="verbatim"> +<pre>mvn clean deploy</pre></div> <p>The same command can be used in a multi-module scenario (i.e. a project with one or more subprojects). Maven traverses into every subproject and executes <code>clean</code>, then executes <code>deploy</code> (including all of the prior build phase steps).</p> <p><i><a href="./introduction-to-the-lifecycle.html">[top]</a>.</i></p></section><section> <h3><a id="A_Build_Phase_is_Made_Up_of_Plugin_Goals">A Build Phase is Made Up of Plugin Goals</a></h3> <p>However, even though a build phase is responsible for a specific step in the build lifecycle, the manner in which it carries out those responsibilities may vary. And this is done by declaring the plugin goals bound to those build phases.</p> <p>A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. The order of execution depends on the order in which the goal(s) and the build phase(s) are invoked. For example, consider the command below. The <code>clean</code> and <code>package</code> arguments are build phases, while the <code>dependency:copy-dependencies</code> is a goal (of a plugin).</p> -<pre>mvn clean dependency:copy-dependencies package</pre> +<div class="verbatim"> +<pre>mvn clean dependency:copy-dependencies package</pre></div> <p>If this were to be executed, the <code>clean</code> phase will be executed first (meaning it will run all preceding phases of the clean lifecycle, plus the <code>clean</code> phase itself), and then the <code>dependency:copy-dependencies</code> goal, before finally executing the <code>package</code> phase (and all its preceding build phases of the default lifecycle).</p> <p>Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.</p> <p>Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it, that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals.</p> @@ -247,7 +247,7 @@ <p>As you will see in the later sections, plugins can contain information that indicates which lifecycle phase to bind a goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want to run as part of your build.</p> <p>The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed first, followed by those configured in the POM. Note that you can use the <code><executions></code> element to gain more control over the order of particular goals.</p> <p>For example, the Modello plugin binds by default its goal <code>modello:java</code> to the <code>generate-sources</code> phase (Note: The <code>modello:java</code> goal generates Java source codes). So to use the Modello plugin and have it generate sources from a model and incorporate that into the build, you would add the following to your POM in the <code><plugins></code> section of <code><build></code>:</p> -<pre><code> <plugin> +<div class="verbatim source"><pre class="prettyprint linenums"> <plugin> <groupId>org.codehaus.modello</groupId> <artifactId>modello-maven-plugin</artifactId> <version>1.8.1</version> @@ -264,11 +264,11 @@ </goals> </execution> </executions> - </plugin></code></pre> + </plugin></pre></div> <p>You might be wondering why that <code><executions></code> element is there. That is so that you can run the same goal multiple times with different configuration if needed. Separate executions can also be given an ID so that during inheritance or the application of profiles you can control whether goal configuration is merged or turned into an additional execution.</p> <p>When multiple executions are given that match a particular phase, they are executed in the order specified in the POM, with inherited executions running first.</p> <p>Now, in the case of <code>modello:java</code>, it only makes sense in the <code>generate-sources</code> phase. But some goals can be used in more than one phase, and there may not be a sensible default. For those, you can specify the phase yourself. For example, let's say you have a goal <code>display:time</code> that echos the current time to the commandline, and you want it to run in the <code>process-test-resources</code> phase to indicate when the tests were started. This would be configured like so:</p> -<pre><code> <plugin> +<div class="verbatim source"><pre class="prettyprint linenums"> <plugin> <groupId>com.mycompany.example</groupId> <artifactId>display-maven-plugin</artifactId> <version>1.0</version> @@ -280,10 +280,10 @@ </goals> </execution> </executions> - </plugin></code></pre> + </plugin></pre></div> <p><i><a href="./introduction-to-the-lifecycle.html">[top]</a>.</i></p></section></section><section> <h2><a id="Lifecycle_Reference">Lifecycle Reference</a></h2> -<p>The following lists all build phases of the <code>default</code>, <code>clean</code> and <code>site</code> lifecycles, which are executed in the order given up to the point of the one specified.</p><section><a id="Clean_Lifecycle"></a> +<p>The following lists all build phases of the <code>default</code>, <code>clean</code> and <code>site</code> lifecycles, which are executed in the order given up to the point of the one specified.</p><section> <h3>Clean Lifecycle</h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -297,7 +297,7 @@ <td style="text-align: left;">remove all files generated by the previous build</td></tr> <tr class="b"> <td style="text-align: left;"><code>post-clean</code></td> -<td style="text-align: left;">execute processes needed to finalize the project cleaning</td></tr></table></section><section><a id="Default_Lifecycle"></a> +<td style="text-align: left;">execute processes needed to finalize the project cleaning</td></tr></table></section><section> <h3>Default Lifecycle</h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -371,7 +371,7 @@ <td style="text-align: left;">install the package into the local repository, for use as a dependency in other projects locally.</td></tr> <tr class="b"> <td style="text-align: left;"><code>deploy</code></td> -<td style="text-align: left;">done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.</td></tr></table></section><section><a id="Site_Lifecycle"></a> +<td style="text-align: left;">done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.</td></tr></table></section><section> <h3>Site Lifecycle</h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -391,7 +391,7 @@ <td style="text-align: left;">deploy the generated site documentation to the specified web server</td></tr></table> <p><i><a href="./introduction-to-the-lifecycle.html">[top]</a>.</i></p></section></section><section> <h2><a id="Built-in_Lifecycle_Bindings">Built-in Lifecycle Bindings</a></h2> -<p>Some phases have goals bound to them by default. And for the default lifecycle, these bindings depend on the packaging value. Here are some of the goal-to-build-phase bindings.</p><section><a id="Clean_Lifecycle_Bindings"></a> +<p>Some phases have goals bound to them by default. And for the default lifecycle, these bindings depend on the packaging value. Here are some of the goal-to-build-phase bindings.</p><section> <h3>Clean Lifecycle Bindings</h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -399,7 +399,7 @@ <th>plugin:goal</th></tr> <tr class="b"> <td style="text-align: left;"><code>clean</code></td> -<td style="text-align: left;"><code>clean:clean</code></td></tr></table></section><section><a id="Default_Lifecycle_Bindings_-_Packaging_ejb_.2F_ejb3_.2F_jar_.2F_par_.2F_rar_.2F_war"></a> +<td style="text-align: left;"><code>clean:clean</code></td></tr></table></section><section> <h3>Default Lifecycle Bindings - Packaging <code>ejb</code> / <code>ejb3</code> / <code>jar</code> / <code>par</code> / <code>rar</code> / <code>war</code></h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -428,7 +428,7 @@ <td style="text-align: left;"><code>install:install</code></td></tr> <tr class="a"> <td style="text-align: left;"><code>deploy</code></td> -<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section><a id="Default_Lifecycle_Bindings_-_Packaging_ear"></a> +<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section> <h3>Default Lifecycle Bindings - Packaging <code>ear</code></h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -448,7 +448,7 @@ <td style="text-align: left;"><code>install:install</code></td></tr> <tr class="b"> <td style="text-align: left;"><code>deploy</code></td> -<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section><a id="Default_Lifecycle_Bindings_-_Packaging_maven-plugin"></a> +<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section> <h3>Default Lifecycle Bindings - Packaging <code>maven-plugin</code></h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -480,7 +480,7 @@ <td style="text-align: left;"><code>install:install</code></td></tr> <tr class="b"> <td style="text-align: left;"><code>deploy</code></td> -<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section><a id="Default_Lifecycle_Bindings_-_Packaging_pom"></a> +<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section> <h3>Default Lifecycle Bindings - Packaging <code>pom</code></h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -494,7 +494,7 @@ <td style="text-align: left;"><code>install:install</code></td></tr> <tr class="b"> <td style="text-align: left;"><code>deploy</code></td> -<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section><a id="Site_Lifecycle_Bindings"></a> +<td style="text-align: left;"><code>deploy:deploy</code></td></tr></table></section><section> <h3>Site Lifecycle Bindings</h3> <table class="table table-bordered table-striped"> <tr class="a"> @@ -505,7 +505,7 @@ <td style="text-align: left;"><code>site:site</code></td></tr> <tr class="a"> <td style="text-align: left;"><code>site-deploy</code></td> -<td style="text-align: left;"><code>site:deploy</code></td></tr></table></section><section><a id="References"></a> +<td style="text-align: left;"><code>site:deploy</code></td></tr></table></section><section> <h3>References</h3> <p>The full Maven lifecycle is defined by the <code>components.xml</code> file in the <code>maven-core</code> module, with <a href="/ref/current/maven-core/lifecycles.html">associated documentation</a> for reference.</p> <p>Default lifecycle bindings are defined in a separate <code><a class="externalLink" href="https://github.com/apache/maven/blob/master/maven-core/src/main/resources/META-INF/plexus/default-bindings.xml";>default-bindings.xml</a></code> descriptor.</p>
