You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2009/06/11 00:41:20 UTC
svn commit: r783561 -
/maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt
Author: jdcasey
Date: Wed Jun 10 22:41:19 2009
New Revision: 783561
URL: http://svn.apache.org/viewvc?rev=783561&view=rev
Log:
[MNG-3401][MNG-3203] Adding a mini-guide to show how to use new executionIds for these issues.
Added:
maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt (with props)
Added: maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt?rev=783561&view=auto
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt (added)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt Wed Jun 10 22:41:19 2009
@@ -0,0 +1,208 @@
+ ---
+ Guide to Configuring Default Mojo Executions
+ ---
+ John Casey
+ ---
+ 10 June 2009
+ ---
+
+Guide to Configuring Default Mojo Executions
+
+ In most cases where you need to configure a plugin, there are two options that work well: plugin-level configuration and execution-level configuration.
+ Plugin-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default
+ lifecycle, or that use a common configuration across all invocations. In fact, for direct invocation from the command line, plugin-level configuration
+ has been the <only> option historically.
+
+ On the other hand, in cases where a more advanced build process requires the execution of mojos - sometimes the same mojos, sometimes different ones -
+ from a single plugin that use different configurations, the execution-level configuration is most commonly used. These cases normally involve plugins
+ that are introduced as part of the standard build process, but which aren't present in the default lifecycle mapping for that particular packaging. In
+ these cases, common settings shared between executions are still normally specified in the plugin-level configuration.
+
+ However, these two options leave out a few important configuration use cases:
+
+ # Mojos run from the command line <and> during the build, when the CLI-driven invocation requires its own configuration.
+
+ # Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases
+ where the same mojos need to be added to a second execution with different configuration.
+
+ # Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but
+ require separate configurations.
+
+ []
+
+ Originally, the default value of the executionId - literally set to <<<default>>> in the POM model - was meant to provide some of this functionality.
+ Unfortunately, this solution was never tested to make sure it worked with the use cases above; they fell through the cracks during testing. Now,
+ with the release of Maven 2.2.0 (and later, Maven 3.0), these use cases can finally be addressed.
+
+*Default <<<executionId>>>s for Implied Executions
+
+ When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable
+ to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've
+ implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Starting in Maven 2.2.0, each
+ mojo invoked directly from the command line will have an execution Id of <<<default-cli>>> assigned to it, which will allow the configuration
+ of that execution from the POM by using this default execution Id. Likewise, each mojo bound to the build lifecycle via the default lifecycle
+ mapping for the specified POM packaging will have an execution Id of <<<default-\<goalName\>>>> assigned to it, to allow configuration of each
+ default mojo execution independently.
+
+**Example: Command-line variant invocation of the assembly plugin
+
+ Consider the case where the user wants to execute the <<<assembly:assembly>>> mojo directly on the command line, but already
+ has a configuration for the <<<assembly:single>>> mojo that runs during the main build lifecycle. Since these configurations require different
+ options, the user cannot use the plugin-level configuration section to specify common elements.
+
+ In this case, the assembly-plugin configuration might look like this:
+
++---+
+<plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <tarLongFileMode>gnu</tarLongFileMode>
+ </configuration>
+ <executions>
+ <execution>
+ <id>build-distros</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ <configuration>
+ <descriptors>
+ <descriptor>src/main/assembly/bin.xml</descriptor>
+ <descriptor>src/main/assembly/src.xml</descriptor>
+ </descriptors>
+ </configuration>
+ </execution>
+ <execution>
+ <id>default-cli</id>
+ <configuration>
+ <descriptorRefs>
+ <descriptorRef>jar-with-dependencies</descriptorRef>
+ <descriptorRef>project</descriptorRef>
+ </descriptorRefs>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
++---+
+
+ In the above example, you can see several interesting things. First, the main build process will invoke the <<<assembly:single>>> mojo during
+ the <<<package>>> phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with
+ the project. Second, all invocations of the assembly plugin should use a <<<tarLongFileMode>>> strategy of <<<gnu>>>. Finally, when the assembly
+ plugin is invoked from the command line, it will build the standard <<<jar-with-dependencies>>> and <<<project>>> artifacts for the project,
+ and ignore the custom assembly descriptors in <<<src/main/assembly>>>.
+
+ Now, notice the difference in the way the two execution blocks reference assembly descriptors. One uses custom descriptors via the <<<descriptors>>>
+ section, and the other uses standard descriptors via the <<<descriptorRefs>>> section. These two sections cannot override one another, so it's
+ impossible to setup one section - say, <<<descriptorRefs>>> - in the plugin-level configuration block (to provide CLI access to it, as historical
+ versions of Maven would require), then have the <<<build-distros>>> invocation override it with the custom descriptors specified in the
+ <<<descriptors>>> section. This configuration is not possible in versions of Maven before 2.2.0.
+
+**Example: Configuring <<<compile>>> to run twice
+
+ In this scenario, the user wants to run the <<<compiler:compile>>> mojo twice for his <<<jar>>> packaging project. The main reason for this
+ is to provide an entry point into the application that will warn the user if he's using a Java version older than 1.5, then exit gracefully.
+ Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1.4 or older
+ JRE.
+
+ Therefore, the user needs to compile tha bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point)
+ to target an older specification...say, 1.3. The first execution will specify the <<<source>>> and <<<target>>> values at <<<1.5>>>,
+ and add an <<<excludes>>> section to avoid compiling the entry point for the application. The second pass will then re-specify <<<source>>>
+ and <<<target>>> to <<<1.3>>>, and basically invert the original <<<excludes>>> section to be an <<<includes>>> section, so as to compile <only>
+ the entry point class.
+
+ The resulting configuration might look something like this:
+
++---+
+<plugin>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ </configuration>
+ <executions>
+ <execution>
+ <id>default-compile</id>
+ <configuration>
+ <excludes>
+ <exclude>**/cli/*</exclude>
+ </excludes>
+ </configuration>
+ </execution>
+ <execution>
+ <id>build-java14-cli</id>
+ <phase>compile</phase>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <source>1.3</source>
+ <target>1.3</target>
+ <includes>
+ <include>**/cli/*</include>
+ </includes>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
++---+
+
+ There are three important things to notice in the above compiler-plugin configuration:
+
+ # The default <<<source>>> and <<<target>>> compatibility levels are for Java 1.5. This means that the compiler will generate binaries
+ for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden.
+
+ # The default pass of the <<<compile>>> goal will <exclude> the <<<**/cli/*>>> path pattern, but will compile everything else in
+ <<<src/main/java>>> to run under Java 1.5.
+
+ # The second pass of the <<<compile>>> mojo - in the execution called <<<build-java14-cli>>> - resets the <<<source>>> and <<<target>>>
+ versions to <<<1.3>>>, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce
+ 1.4-targeted binaries for the classes matching the <<<**/cli/*>>> path pattern.
+
+ []
+
+ Note that prior to Maven 2.2.0, it was much more difficult - if not impossible - to compile different subpaths within your project's
+ codebase to target different Java versions.
+
+**Example: Configuring <<<compile>>> and <<<testCompile>>> mojos separately
+
+ Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target
+ version 1.4 of the Java specification as his runtime platform. However, he still wants the convenience and other advantages to be found in
+ a unit-testing framework like TestNG. This forces the user to configure the <<<compile>>> mojo with one set of <<<source>>> and <<<target>>>
+ values - specifically, <<<1.4>>> - and the <<<testCompile>>> mojo with another (<<<1.5>>>).
+
+ The resulting compiler-plugin configuration might look something like the following:
+
++---+
+<plugin>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>default-compile</id>
+ <configuration>
+ <source>1.3</source>
+ <target>1.3</target>
+ </configuration>
+ </execution>
+ <execution>
+ <id>default-testCompile</id>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
++---+
+
+ This example is fairly simple and straightforward. First, the <<<default-compile>>> execution sets the <<<source>>> and <<<target>>> values to <<<1.3>>>
+ to allow older Java versions to run the project. Then, the <<<default-testCompile>>> execution resets the <<<source>>> and <<<target>>> values to
+ <<<1.5>>>, which enables the project to use tools like TestNG that use annotations.
+
+ Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1.3 by default, so
+ the only configuration that's really required is the <<<default-testCompile>>> execution. The <<<default-compile>>> execution respecifies plugin
+ defaults. The only time this might be useful is when a parent POM defines a plugin-level configuration for <<<source>>> and <<<target>>> that needs
+ to be changed for the purposes of these different compiler executions. This example is meant to be illustrative of the potential for separate configuration
+ of default lifecycle mojos to be found in Maven 2.2.0.
+
+ Again, the above configuration would not be possible in older versions of Maven. Starting with Maven 2.2.0, these advanced configurations have become
+ a reality.
Propchange: maven/site/trunk/src/site/apt/guides/mini/guide-default-execution-ids.apt
------------------------------------------------------------------------------
svn:eol-style = native