You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by bi...@apache.org on 2011/07/01 19:49:31 UTC
svn commit: r1142008 - in
/maven/plugins/trunk/maven-shade-plugin/src/site/apt:
examples/resource-transformers.apt.vm usage.apt.vm
Author: bimargulies
Date: Fri Jul 1 17:49:31 2011
New Revision: 1142008
URL: http://svn.apache.org/viewvc?rev=1142008&view=rev
Log:
[MSHADE-100]: (Robert Burrell Donkin): add documentation on the provided transformer classes.
Modified:
maven/plugins/trunk/maven-shade-plugin/src/site/apt/examples/resource-transformers.apt.vm
maven/plugins/trunk/maven-shade-plugin/src/site/apt/usage.apt.vm
Modified: maven/plugins/trunk/maven-shade-plugin/src/site/apt/examples/resource-transformers.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-shade-plugin/src/site/apt/examples/resource-transformers.apt.vm?rev=1142008&r1=1142007&r2=1142008&view=diff
==============================================================================
--- maven/plugins/trunk/maven-shade-plugin/src/site/apt/examples/resource-transformers.apt.vm (original)
+++ maven/plugins/trunk/maven-shade-plugin/src/site/apt/examples/resource-transformers.apt.vm Fri Jul 1 17:49:31 2011
@@ -29,7 +29,29 @@ Resource Transformers
overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource
transformers kick in.
-* Merging Plexus Component Descriptors
+
+*-----------------------------------------+--------------------------------------+
+| {{ApacheLicenseResourceTransformer}} | Prevents license duplication |
+*-----------------------------------------+--------------------------------------+
+| ApacheNoticeResourceTransformer | Prepares merged NOTICE |
+*-----------------------------------------+--------------------------------------+
+| {{AppendingTransformer}} | Adds content to a resource |
+*-----------------------------------------+--------------------------------------+
+| {{ComponentsXmlResourceTransformer}} | Aggregates Plexus <<<components.xml>>>|
+*-----------------------------------------+--------------------------------------+
+| {{DontIncludeResourceTransformer}} | Prevents inclusion of matching resources |
+*-----------------------------------------+--------------------------------------+
+| {{IncludeResourceTransformer}} | Adds files from the project |
+*-----------------------------------------+--------------------------------------+
+| {{ManifestResourceTransformer}} | Sets entries in the <<<MANIFEST>>> |
+*-----------------------------------------+--------------------------------------+
+| {{ServicesResourceTransformer}} | Merges <<<META-INF/services>>> resources |
+*-----------------------------------------+--------------------------------------+
+| {{XmlAppendingTransformer}} | Adds XML content to an XML resource |
+*-----------------------------------------+--------------------------------------+
+Transformers in <<<org.apache.maven.plugins.shade.resource>>>
+
+* Merging Plexus Component Descriptors with the {ComponentsXmlResourceTransformer}
JARs for components targeting the Plexus IoC container contain a <<<META-INF/plexus/components.xml>>> entry that
declares the component and its requirements. If the uber JAR aggregates multiple Plexus components, a
@@ -67,7 +89,7 @@ Resource Transformers
Since plugin version 1.3, this resource transformer will also update the descriptor to account for relocation of
component interfaces/implementations (if any).
-* Concatenating Service Entries
+* Concatenating Service Entries with the {ServicesResourceTransformer}
JAR files providing implementations of some interfaces often ship with a <<<META-INF/services/>>> directory that
maps interfaces to their implementation classes for lookup by the service locator. To merge multiple implementations
@@ -102,7 +124,7 @@ Resource Transformers
</project>
+-----
-* Merging Content of Specific Files
+* Merging Content of Specific Files with {AppendingTransformer} and XmlAppendingTransformer
Some jars contain additional resources (such as properties files) that have the same file name. To avoid overwriting, you can
opt to merge them by appending their content into one file. One good example for this is when aggregating both the spring-context
@@ -143,7 +165,7 @@ Resource Transformers
</project>
+-----
- For XML files, you can use the <<<XmlAppendingTransformer>>> instead:
+ For XML files, you can use the <<<{XmlAppendingTransformer}>>> instead:
+-----
<project>
@@ -184,3 +206,177 @@ Resource Transformers
transformation, e.g. when using the Crimson XML parser as used in some JRE 1.4. If the transformed resource uses
external entities, DTD resolution can either be turned back on or a plugin dependency on <<<xerces:xercesImpl:2.9.1>>>
is added to the POM.
+
+* Excluding Resources with the {DontIncludeResourceTransformer}
+
+ The <<<DontIncludeResourceTransformer>>> allows resources to be excluded when
+ their name ends in a given value.
+
+ For example, the following sample excludes all resources ending in <<<.txt>>>.
+
++-----
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.DontIncludeResourceTransformer">
+ <resource>.txt</resource>
+ </transformer>
+ </transformers>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----
+
+* Adding New Resources with the {IncludeResourceTransformer}
+
+ The <<<IncludeResourceTransformer>>> allows project files to be included in
+ the package under a given name.
+
+ For example, the following sample includes <<<README.txt>>> in the package
+ as <<<README>>> in the <<<META-INF>>> directory.
+
++-----
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.IncludeResourceTransformer">
+ <resource>META-INF/README</resource>
+ <file>README.txt</file>
+ </transformer>
+ </transformers>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----
+
+
+* Setting Manifest Entries with the {ManifestResourceTransformer}
+
+ The <<<ManifestResourceTransformer>>> allows existing entries in the <<<MANIFEST>>>
+ to be replaced and new entries added.
+
+ For example, the following sample sets
+
+ * the <<<Main-Class>>> entry to the value of the <<<app.main.class>>> property,
+
+ * the <<<X-Compile-Source-JDK>>> entry to the value of the <<<maven.compile.source>>> property and
+
+ * the <<<X-Compile-Target-JDK>>> entry to the value of the <<<maven.compile.target>>> property.
+
+
++-----
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+ <manifestEntries>
+ <Main-Class>${app.main.class}</Main-Class>
+ <X-Compile-Source-JDK>${maven.compile.source}</X-Compile-Source-JDK>
+ <X-Compile-Target-JDK>${maven.compile.target}</X-Compile-Target-JDK>
+ </manifestEntries>
+ </transformer>
+ </transformers>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----
+
+
+* Licensing
+
+** Preventing License Duplication with the {ApacheLicenseResourceTransformer}
+
+ Some open source producers
+ (including the {{{http://www.apache.org} Apache Software Foundation}})
+ include a copy of their license in the META-INF directory. These are conventionally named
+ either <<<LICENSE>>> or <<<LICENSE.txt>>>. When merging these dependencies, adding these
+ resources may cause confusion.
+ The <<<ApacheLicenseResourceTransformer>>> ensures that duplicate licenses (named according
+ to this convention) are not merged.
+
+ For example, the following prevents the license from a <<<commons-collections>>> dependency
+ being merged in
+
++-----
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.ApacheLicenseResourceTransformer">
+ </transformer>
+ </transformers>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----
Modified: maven/plugins/trunk/maven-shade-plugin/src/site/apt/usage.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-shade-plugin/src/site/apt/usage.apt.vm?rev=1142008&r1=1142007&r2=1142008&view=diff
==============================================================================
--- maven/plugins/trunk/maven-shade-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-shade-plugin/src/site/apt/usage.apt.vm Fri Jul 1 17:49:31 2011
@@ -62,3 +62,28 @@ mvn package
...
</project>
+-----
+
+* Resource Transformers
+
+*-----------------------------------------+--------------------------------------+
+| ApacheLicenseResourceTransformer | Prevents license duplication |
+*-----------------------------------------+--------------------------------------+
+| ApacheNoticeResourceTransformer | Prepares merged NOTICE |
+*-----------------------------------------+--------------------------------------+
+| AppendingTransformer | Adds content to a resource |
+*-----------------------------------------+--------------------------------------+
+| ComponentsXmlResourceTransformer | Aggregates Plexus <<<components.xml>>>|
+*-----------------------------------------+--------------------------------------+
+| DontIncludeResourceTransformer | Prevents inclusion of matching resources |
+*-----------------------------------------+--------------------------------------+
+| IncludeResourceTransformer | Adds files from the project |
+*-----------------------------------------+--------------------------------------+
+| ManifestResourceTransformer | Sets entries in the <<<MANIFEST>>> |
+*-----------------------------------------+--------------------------------------+
+| ServicesResourceTransformer | Merges <<<META-INF/services>>> resources |
+*-----------------------------------------+--------------------------------------+
+| XmlAppendingTransformer | Adds XML content to an XML resource |
+*-----------------------------------------+--------------------------------------+
+Transformers in <<<org.apache.maven.plugins.shade.resource>>>
+
+ For more information, see {{{./examples/resource-transformers.html}samples}}.