This is an automated email from the ASF dual-hosted git repository. elharo pushed a commit to branch fix-doc-issues-merged in repository https://gitbox.apache.org/repos/asf/maven-shade-plugin.git
commit 20c87547d52fccd5d14710a262c95acf5736a737 Merge: e72e2f8 8edd64a Author: Elliotte Rusty Harold <[email protected]> AuthorDate: Sun Nov 1 13:10:22 2026 +0000 Merge branch 'master' into fix-doc-issues .asf.yaml | 32 + .github/dependabot.yml | 24 + .github/pull_request_template.md | 32 +- .github/workflows/maven-verify.yml | 3 +- .github/workflows/pr-automation.yml | 6 +- .../workflows/{maven-verify.yml => pr-check.yml} | 14 +- .../workflows/{maven-verify.yml => pr-signal.yml} | 18 +- pom.xml | 89 +- .../MSHADE-105/{verify.bsh => verify.groovy} | 0 src/it/projects/MSHADE-183/pom.xml | 2 +- .../MSHADE-183/{verify.bsh => verify.groovy} | 0 src/it/projects/MSHADE-215/app/pom.xml | 68 + src/it/projects/MSHADE-215/base/pom.xml | 32 + .../apache/maven/its/shade/mshade215/Base.java} | 11 +- .../it/projects/MSHADE-215/invoker.properties | 14 +- src/it/projects/MSHADE-215/pom.xml | 50 + .../setup.bsh => MSHADE-215/verify.groovy} | 15 +- .../{verify.bsh => verify.groovy} | 8 +- .../MSHADE-316/{verify.bsh => verify.groovy} | 8 +- .../MSHADE-351/{verify.bsh => verify.groovy} | 0 .../pom.xml | 2 +- .../{verify.bsh => verify.groovy} | 8 +- src/it/projects/MSHADE-368/pom.xml | 67 + src/it/projects/MSHADE-368/verify.groovy | 39 + src/it/projects/MSHADE-373/pom.xml | 2 +- .../MSHADE-373/{verify.bsh => verify.groovy} | 4 +- .../projects/MSHADE-374_testJarArtifactSet/pom.xml | 1 + .../{verify.bsh => verify.groovy} | 8 +- .../pom.xml | 55 +- .../src/main/resources/META-INF/NOTICE | 1 + .../verify.groovy} | 17 +- src/it/projects/apache-notice-project-name/pom.xml | 52 + .../src/main/resources/META-INF/NOTICE | 1 + .../verify.groovy} | 23 +- .../{verify.bsh => verify.groovy} | 8 +- .../pom.xml | 50 +- .../verify.groovy} | 14 +- .../projects/attach-after-lifecycle-fork/pom.xml | 2 +- .../{setup.bsh => setup.groovy} | 0 .../{verify.bsh => verify.groovy} | 4 +- src/it/projects/attached-artifact-type/pom.xml | 2 +- .../component-descriptor-relocation/app/pom.xml | 2 +- .../component-descriptor-relocation/pom.xml | 2 +- .../dep-reduced-pom-relocated-result/pom.xml | 2 +- .../dep-reduced-pom-with-local-parent/pom.xml | 2 +- .../duplicate-classes-with-reloc/app/pom.xml | 2 +- .../duplicate-classes-without-reloc/app/pom.xml | 2 +- .../extrajar/{verify.bsh => verify.groovy} | 4 +- .../{verify.bsh => verify.groovy} | 8 +- .../{setup.bsh => setup.groovy} | 0 .../{verify.bsh => verify.groovy} | 0 .../finalNameBuild/{setup.bsh => setup.groovy} | 0 .../finalNameBuild/{verify.bsh => verify.groovy} | 0 .../{setup.bsh => setup.groovy} | 0 .../{verify.bsh => verify.groovy} | 0 .../finalNameShade/{setup.bsh => setup.groovy} | 0 .../finalNameShade/{verify.bsh => verify.groovy} | 0 .../{verify.bsh => verify.groovy} | 4 +- .../include-resource-existing-entry/README.txt | 1 + .../pom.xml | 55 +- .../src/main/resources/META-INF/README.txt | 1 + .../verify.groovy} | 18 +- .../invoker.properties | 13 +- .../pom.xml | 54 +- .../verify.groovy} | 13 +- src/it/projects/manifest-retained/pom.xml | 2 +- .../{verify.bsh => verify.groovy} | 0 src/it/projects/manifest-transformed/pom.xml | 2 +- .../{verify.bsh => verify.groovy} | 0 .../mini-jar-jdk11+/{verify.bsh => verify.groovy} | 10 +- .../{verify.bsh => verify.groovy} | 7 +- .../{verify.bsh => verify.groovy} | 8 +- .../mini-jar/{verify.bsh => verify.groovy} | 8 +- src/it/projects/module-info-merge/app/pom.xml | 107 ++ .../app/src/main/java/app/api/Application.java} | 16 +- .../app/src/main/java/module-info.java} | 15 +- .../projects/module-info-merge/automatic/pom.xml | 54 + .../java/automatic/library/AutomaticLibrary.java} | 26 +- .../java/automatic/library/AutomaticProvider.java} | 17 +- .../services/external.api.AutomaticService | 1 + src/it/projects/module-info-merge/embedded/pom.xml | 37 + .../src/main/java/embedded/api/Library.java} | 14 +- .../src/main/java/embedded/internal/Provider.java} | 17 +- .../embedded/src/main/java/module-info.java} | 16 +- src/it/projects/module-info-merge/external/pom.xml | 30 + .../main/java/external/api/AutomaticService.java} | 14 +- .../src/main/java/external/api/Service.java} | 14 +- .../external/src/main/java/module-info.java} | 14 +- .../projects/module-info-merge/invoker.properties | 14 +- src/it/projects/module-info-merge/pom.xml | 72 + src/it/projects/module-info-merge/verify.groovy | 107 ++ .../{verify.bsh => verify.groovy} | 8 +- .../pom-packaging/{verify.bsh => verify.groovy} | 7 +- .../{verify.bsh => verify.groovy} | 4 +- .../reloc-abs-resource-path-exclude/pom.xml | 2 +- src/it/projects/reloc-abs-resource-path/pom.xml | 2 +- .../reloc-and-mini/{verify.bsh => verify.groovy} | 8 +- src/it/projects/reloc-anno/pom.xml | 4 +- .../projects/reloc-class-from-string-pool/pom.xml | 4 +- src/it/projects/reloc-enum-ref-from-anno/pom.xml | 4 +- .../{verify.bsh => verify.groovy} | 8 +- src/it/projects/rerun-with-reloc/pom.xml | 2 +- src/it/projects/rerun-without-reloc/pom.xml | 2 +- .../{verify.bsh => verify.groovy} | 2 +- .../{verify.bsh => verify.groovy} | 0 .../projects/shading-with-java-8-sources/pom.xml | 2 +- .../projects/shading-with-release-sources/pom.xml | 2 +- .../{verify.bsh => verify.groovy} | 4 +- .../plugins/shade/AutomaticModuleAnalyzer.java | 246 +++ .../apache/maven/plugins/shade/DefaultShader.java | 216 ++- .../plugins/shade/ModuleInfoConfiguration.java | 194 ++ .../apache/maven/plugins/shade/ModuleInfoMode.java | 51 + .../maven/plugins/shade/ModuleInfoProcessor.java | 1993 ++++++++++++++++++++ .../plugins/shade/ModuleInfoPublicBoundary.java | 51 + .../maven/plugins/shade/PlatformModuleIndex.java | 200 ++ .../apache/maven/plugins/shade/ShadeRequest.java | 91 +- .../org/apache/maven/plugins/shade/Shader.java | 2 +- .../apache/maven/plugins/shade/filter/Filter.java | 8 +- .../maven/plugins/shade/filter/MinijarFilter.java | 15 +- .../maven/plugins/shade/filter/SimpleFilter.java | 37 +- .../maven/plugins/shade/mojo/ArtifactSelector.java | 59 +- .../maven/plugins/shade/mojo/RelativizePath.java | 8 +- .../apache/maven/plugins/shade/mojo/ShadeMojo.java | 240 ++- .../apache/maven/plugins/shade/pom/Counter.java | 11 +- .../maven/plugins/shade/pom/MavenJDOMWriter.java | 473 ++--- .../maven/plugins/shade/relocation/Relocator.java | 4 +- .../plugins/shade/relocation/SimpleRelocator.java | 4 +- .../resource/ApacheLicenseResourceTransformer.java | 2 +- .../resource/ApacheNoticeResourceTransformer.java | 36 +- .../shade/resource/GroovyResourceTransformer.java | 4 +- .../shade/resource/IncludeResourceTransformer.java | 10 +- .../resource/ManifestResourceTransformer.java | 105 +- .../resource/ReproducibleResourceTransformer.java | 11 +- .../ResourceBundleAppendingTransformer.java | 7 +- .../shade/resource/ResourceTransformer.java | 15 +- .../resource/ServicesResourceTransformer.java | 15 + src/site/apt/examples/attached-artifact.apt.vm | 60 - src/site/apt/examples/class-relocation.apt.vm | 95 - src/site/apt/examples/use-shader-other-impl.apt.vm | 106 -- src/site/apt/index.apt.vm | 76 - src/site/apt/usage.apt.vm | 95 - src/site/fml/faq.fml | 43 - src/site/markdown/examples/attached-artifact.md.vm | 59 + src/site/markdown/examples/class-relocation.md.vm | 88 + .../examples/executable-jar.md.vm} | 63 +- .../examples/includes-excludes.md.vm} | 87 +- .../markdown/examples/module-info-merging.md.vm | 203 ++ .../examples/resource-transformers.md.vm} | 359 ++-- .../markdown/examples/use-shader-other-impl.md.vm | 107 ++ src/site/markdown/faq.md | 39 + src/site/markdown/index.md | 55 + src/site/markdown/usage.md.vm | 87 + src/site/site.xml | 1 + .../maven/plugins/shade/DefaultShaderTest.java | 1415 +++++++++++++- .../plugins/shade/ModuleInfoConfigurationTest.java | 630 +++++++ .../maven/plugins/shade/ModuleInfoModeTest.java | 47 + .../plugins/shade/PlatformModuleIndexTest.java | 124 ++ .../plugins/shade/filter/MinijarFilterTest.java | 39 +- .../plugins/shade/filter/SimpleFilterTest.java | 6 +- .../maven/plugins/shade/mojo/ArtifactIdTest.java | 8 +- .../plugins/shade/mojo/ArtifactSelectorTest.java | 42 +- .../shade/mojo/OutputTimestampYearTest.java | 49 + .../plugins/shade/mojo/RelativizePathTest.java | 6 +- .../maven/plugins/shade/mojo/ShadeMojoTest.java | 137 +- .../shade/pom/PomWriterRelativePathTest.java | 84 + .../relocation/SimpleRelocatorParameterTest.java | 4 +- .../shade/relocation/SimpleRelocatorTest.java | 8 +- .../ApacheLicenseResourceTransformerTest.java | 10 +- .../ApacheNoticeResourceTransformerTest.java | 71 +- .../shade/resource/AppendingTransformerTest.java | 10 +- .../ComponentsXmlResourceTransformerTest.java | 26 +- .../resource/GroovyResourceTransformerTest.java | 10 +- .../resource/IncludeResourceTransformerTest.java | 88 + .../resource/ManifestResourceTransformerTest.java | 35 +- .../ResourceBundleAppendingTransformerTest.java | 10 +- .../resource/ServiceResourceTransformerTest.java | 8 +- .../resource/XmlAppendingTransformerTest.java | 10 +- .../properties/PropertiesTransformerTest.java | 15 +- .../shade/resource/rule/TransformerTesterRule.java | 76 +- src/test/projects/test-project/pom.xml | 2 +- 180 files changed, 8473 insertions(+), 1884 deletions(-) diff --cc src/site/markdown/examples/class-relocation.md.vm index 0000000,9153a38..d56a840 mode 000000,100644..100644 --- a/src/site/markdown/examples/class-relocation.md.vm +++ b/src/site/markdown/examples/class-relocation.md.vm @@@ -1,0 -1,88 +1,88 @@@ + --- + title: Relocating Classes + author: + - Mauro Talevi + date: 2008-07-21 + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + # Relocating Classes + + If the uber JAR is reused as a dependency of some other project, directly including classes from the artifact's dependencies in the uber JAR can cause class loading conflicts due to duplicate classes on the class path. To address this issue, one can relocate the classes which get included in the shaded artifact in order to create a private copy of their bytecode: + + ```xml + <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> + <relocations> + <relocation> + <pattern>org.codehaus.plexus.util</pattern> + <shadedPattern>org.shaded.plexus.util</shadedPattern> + <excludes> + <exclude>org.codehaus.plexus.util.xml.Xpp3Dom</exclude> + <exclude>org.codehaus.plexus.util.xml.pull.*</exclude> + </excludes> + </relocation> + </relocations> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> + ... + </project> + ``` + + This instructs the plugin to move classes from the package `org.codehaus.plexus.util` and its subpackages into the package `org.shaded.plexus.util` by moving the corresponding JAR file entries and rewriting the affected bytecode. The class `Xpp3Dom` and some others will remain in their original package. + + It's also possible to narrow the pattern with the `include` and/or `exclude` tag: + + ```xml + <project> + ... + <relocation> + <pattern>org.codehaus.plexus.util</pattern> + <shadedPattern>org.shaded.plexus.util</shadedPattern> + <includes> - <include>org.codehaud.plexus.util.io.*</include> ++ <include>org.codehaus.plexus.util.io.*</include> + </includes> + <excludes> - <exclude>org.codehaud.plexus.util.io.*</exclude> ++ <exclude>org.codehaus.plexus.util.io.*</exclude> + </excludes> + </relocation> + ... + </project> + ``` + + # When using relocations with the `rawString` element set to `true`, both `includes` and `excludes` are disregarded but the pattern is treated as [regular expression pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). Also the `pattern` and `shadedPattern` are always referring to a filesystem path (and must use forward slash (`/`) as separator). Both are not normalized in this case. diff --cc src/site/markdown/examples/includes-excludes.md.vm index 400f718,61ed363..2f0355a --- a/src/site/markdown/examples/includes-excludes.md.vm +++ b/src/site/markdown/examples/includes-excludes.md.vm @@@ -150,14 -144,11 +144,11 @@@ Besides user-specified filters, the plu </build> ... </project> - +----- + ``` - As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter. - Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified - classes in that artifact. <<<\<excludeDefaults\>false\<\/excludeDefaults\>>>> will override this behavior so that all - non-specified classes still will be included though. -As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter. Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified classes in that artifact. `<excludeDefaults>false<\excludeDefaults>` will override this behavior so that all non-specified classes still will be included though. ++As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter. Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified classes in that artifact. `<excludeDefaults>false</excludeDefaults>` will override this behavior so that all non-specified classes still will be included though. - +----- + ```xml <project> ... <build> diff --cc src/site/markdown/examples/resource-transformers.md.vm index cfcd630,01b456d..a1c62a9 --- a/src/site/markdown/examples/resource-transformers.md.vm +++ b/src/site/markdown/examples/resource-transformers.md.vm @@@ -1,78 -1,64 +1,64 @@@ - ------ - Resource Transformers - ------ - Mauro Talevi - ------ - 2008-07-21 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - - Resource Transformers - - Aggregating classes/resources from several artifacts into one uber JAR is straightforward as long as there is no - overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource - transformers kick in. - - - *-----------------------------------------+------------------------------------------+ - | {{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 | - *-----------------------------------------+------------------------------------------+ - | {{GroovyResourceTransformer}} | Merges Apache Groovy extends modules | - *-----------------------------------------+------------------------------------------+ - | {{IncludeResourceTransformer}} | Adds files from the project | - *-----------------------------------------+------------------------------------------+ - | {{ManifestResourceTransformer}} | Sets entries in the <<<MANIFEST>>> | - *-----------------------------------------+------------------------------------------+ - | {{PluginXmlResourceTransformer}} | Aggregates Maven's <<<plugin.xml>>> | - *-----------------------------------------+------------------------------------------+ - | {{ResourceBundleAppendingTransformer}} | Merges ResourceBundles | - *-----------------------------------------+------------------------------------------+ - | {{ServicesResourceTransformer}} | Relocated class names in <<<META-INF/services>>> resources and merges them. | - *-----------------------------------------+------------------------------------------+ - | {{XmlAppendingTransformer}} | Adds XML content to an XML resource | - *-----------------------------------------+------------------------------------------+ - Transformers in <<<org.apache.maven.plugins.shade.resource>>> - - *-----------------------------------------+------------------------------------------+ - | {{PropertiesTransformer}} | Merges properties files owning an ordinal to solve conflicts | - *-----------------------------------------+------------------------------------------+ - | {{OpenWebBeansPropertiesTransformer}} | Merges Apache OpenWebBeans configuration files | - *-----------------------------------------+------------------------------------------+ - | {{MicroprofileConfigTransformer}} | Merges conflicting Microprofile Config properties based on an ordinal | - *-----------------------------------------+------------------------------------------+ - Transformers in <<<org.apache.maven.plugins.shade.resource.properties>>> (available since 3.2.2) - - * 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 - <<<ComponentsXmlResourceTransformer>>> needs to be used to merge the XML descriptors: - - +----- + --- + title: Resource Transformers + author: + - Mauro Talevi + date: 2008-07-21 + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + # Resource Transformers + -Aggregating classes/resources from several artifacts into one uber JAR is straight forward as long as there is no overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource transformers kick in. ++Aggregating classes/resources from several artifacts into one uber JAR is straightforward as long as there is no overlap. Otherwise, some kind of logic to merge resources from several JARs is required. This is where resource transformers kick in. + + Each resource is offered to the configured transformers in the order they are listed, and the first transformer that accepts it consumes it: later transformers never see that resource. List a transformer that drops resources, such as `DontIncludeResourceTransformer`, after the transformers that should merge them. + + | | | + |:---|:---| + |[ApacheLicenseResourceTransformer](#ApacheLicenseResourceTransformer)|Prevents license duplication| + |[ApacheNoticeResourceTransformer](#ApacheNoticeResourceTransformer)|Prepares merged NOTICE| + |[AppendingTransformer](#AppendingTransformer)|Adds content to a resource| + |[ComponentsXmlResourceTransformer](#ComponentsXmlResourceTransformer)|Aggregates Plexus `components.xml`| + |[DontIncludeResourceTransformer](#DontIncludeResourceTransformer)|Prevents inclusion of matching resources| + |[GroovyResourceTransformer](#GroovyResourceTransformer)|Merges Apache Groovy extends modules| + |[IncludeResourceTransformer](#IncludeResourceTransformer)|Adds files from the project| + |[ManifestResourceTransformer](#ManifestResourceTransformer)|Sets entries in the `MANIFEST`| -|[PluginXmlResourceTransformer](#PluginXmlResourceTransformer)|Aggregates Mavens `plugin.xml`| ++|[PluginXmlResourceTransformer](#PluginXmlResourceTransformer)|Aggregates Maven's `plugin.xml`| + |[ResourceBundleAppendingTransformer](#ResourceBundleAppendingTransformer)|Merges ResourceBundles| + |[ServicesResourceTransformer](#ServicesResourceTransformer)|Relocated class names in `META-INF/services` resources and merges them.| + |[XmlAppendingTransformer](#XmlAppendingTransformer)|Adds XML content to an XML resource| + Transformers in `org.apache.maven.plugins.shade.resource` + + | | | + |:---|:---| + |[PropertiesTransformer](#PropertiesTransformer)|Merges properties files owning an ordinal to solve conflicts| + |[OpenWebBeansPropertiesTransformer](#OpenWebBeansPropertiesTransformer)|Merges Apache OpenWebBeans configuration files| + |[MicroprofileConfigTransformer](#MicroprofileConfigTransformer)|Merges conflicting Microprofile Config properties based on an ordinal| + `org.apache.maven.plugins.shade.resource.properties` + + Merging Plexus Component Descriptors with the <a id="ComponentsXmlResourceTransformer"></a>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 `ComponentsXmlResourceTransformer` needs to be used to merge the XML descriptors: + + ```xml <project> ... <build> @@@ -98,18 -84,16 +84,16 @@@ </build> ... </project> - +----- + ``` - Since plugin version 1.3, this resource transformer also updates the descriptor to account for relocation of - component interfaces/implementations (if any). -Since plugin version 1.3, this resource transformer will also update the descriptor to account for relocation of component interfaces/implementations (if any). ++Since plugin version 1.3, this resource transformer also updates the descriptor to account for relocation of component interfaces/implementations (if any). - * Relocate classes of the Maven Plugin Descriptor with the {PluginXmlResourceTransformer} + Relocate classes of the Maven Plugin Descriptor with the <a id="PluginXmlResourceTransformer"></a>PluginXmlResourceTransformer + ------------------------------------------------------------------------------------------------------------------------------ - With {{{https://maven.apache.org/plugin-tools/index.html}Plugin Tools 3.0}}, annotations were introduced. References - to classes are now references to java.lang.Class objects rather than strings containing class names. When you wanted to relocate classes, you had to - maintain the <<<META-INF/maven/plugin.xml>>> by hand, but now this can be done with the <<<PluginXmlResourceTransformer>>> -With [Plugin Tools 3.0](http://maven.apache.org/plugin-tools/index.html) annotations have been introduced. Now references to classes are no longer classnames as String, but the actual Class reference. When you wanted to relocate classes, you had to maintain the `META-INF/maven/plugin.xml` by hand, but now this can be done with the `PluginXmlResourceTransformer` ++With [Plugin Tools 3.0](https://maven.apache.org/plugin-tools/index.html), annotations were introduced. References to classes are now references to java.lang.Class objects rather than strings containing class names. When you wanted to relocate classes, you had to maintain the `META-INF/maven/plugin.xml` by hand, but now this can be done with the `PluginXmlResourceTransformer` - +----- + ```xml <project> ... <build> @@@ -171,16 -152,14 +152,14 @@@ JAR files providing implementations of </build> ... </project> - +----- + ``` - * Merging Content of Specific Files with {AppendingTransformer}, XmlAppendingTransformer and ResourceBundleAppendingTransformer + Merging Content of Specific Files with <a id="AppendingTransformer"></a>AppendingTransformer, XmlAppendingTransformer and ResourceBundleAppendingTransformer + ------------------------------------------------------------------------------------------------------------------------------------------------------------ - Some jars contain additional resources (such as properties files) that have the same file name. To avoid overwriting, you can - merge them by appending their content. One good example of this is aggregating both the spring-context - and plexus-spring jars. Both of them have the <<<META-INF/spring.handlers>>> file which is used by Spring to handle XML schema - namespaces. You can merge the contents of all the files with that specific name using the <<<AppendingTransformer>>> as shown below: - - +----- -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 and plexus-spring jars. Both of them have the `META-INF/spring.handlers` file which is used by Spring to handle XML schema namespaces. You can merge the contents of all the files with that specific name using the `AppendingTransformer` [...] ++Some jars contain additional resources (such as properties files) that have the same file name. To avoid overwriting, you can merge them by appending their content. One good example of this is aggregating both the spring-context and plexus-spring jars. Both of them have the `META-INF/spring.handlers` file which is used by Spring to handle XML schema namespaces. You can merge the contents of all the files with that specific name using the `AppendingTransformer` as shown below: + + ```xml <project> ... <build> @@@ -519,17 -479,15 +479,15 @@@ For example, to simply merge in depende </build> ... </project> - +----- + ``` - ** Aggregating Apache Groovy extension modules descriptors with the {GroovyResourceTransformer} + #[[### Aggregating Apache Groovy extension modules descriptors with the <a id="GroovyResourceTransformer"></a>GroovyResourceTransformer]]# - The Apache Groovy language provides extension modules located at - <<<META-INF/services/org.codehaus.groovy.runtime.ExtensionModule>>>, these modules use the property file format. - <<<GroovyResourceTransformer>>> automates the assembly of Groovy extension module descriptors. -The Apache Groovy language provides extension modules located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`, these modules use the property file format. `GroovyResourceTransformer` automates the assembly of Groovy extension modules `NOTICE`. ++The Apache Groovy language provides extension modules located at `META-INF/services/org.codehaus.groovy.runtime.ExtensionModule`, these modules use the property file format. `GroovyResourceTransformer` automates the assembly of Groovy extension module descriptors. - For example, to simply merge the extension modules of several jars: + For example, to simply merge the extension modules of several jars: - +----- + ```xml <project> ... <build> diff --cc src/site/markdown/examples/use-shader-other-impl.md.vm index 0000000,b01fb37..06b2072 mode 000000,100644..100644 --- a/src/site/markdown/examples/use-shader-other-impl.md.vm +++ b/src/site/markdown/examples/use-shader-other-impl.md.vm @@@ -1,0 -1,104 +1,107 @@@ + --- -title: Using an other Shader Implementation ++title: Using another Shader Implementation + author: + - Olivier Lamy + date: 2012-03-13 + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + # Using your own Shader implementation + -By default, the plugin provide a DefaultShader implementation but with version 1.6 you can use your own implementation. ++By default, the plugin provides a DefaultShader implementation. You can, however, use your own implementation. + + Create a standard Maven project with your implementation. + -```unknown - -Dependency to Plexus annotations ++Dependency for Plexus annotations: + ++```xml + <dependency> + <groupId>org.codehaus.plexus</groupId> + <artifactId>plexus-component-annotations</artifactId> + <version>1.5.5</version> + </dependency> ++``` + -Create your Shader ++Create your Shader: + ++```java + @Component( role = Shader.class, hint = "mock" ) + public class MockShader + implements Shader + { + // implement the interface here + } ++``` + -// Use the plexus component metadata plugin in your job to generate Plexus metadata ++Use the Plexus Component Metadata plugin in your build to generate Plexus metadata: + ++```xml + <plugin> + <groupId>org.codehaus.plexus</groupId> + <artifactId>plexus-component-metadata</artifactId> + <version>1.5.5</version> + <executions> + <execution> + <goals> + <goal>generate-metadata</goal> + </goals> + </execution> + </executions> + </plugin> + ``` + + Assuming your project has coordinate org.foo.bar:wine:1.0, you must add it as a dependency of the shade plugin. + + ```xml + <project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-shade-plugin</artifactId> + <version>${project.version}</version> + <dependencies> + <dependency> + <groupId>org.foo.bar</groupId> + <artifactId>wine</artifactId> + <version>1.0</version> + </dependency> + </dependencies> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>shade</goal> + </goals> + <configuration> + <shaderHint>mock</shaderHint> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> + ... + </project> + ``` + + Now the mojo will use your own implementation. diff --cc src/site/markdown/faq.md index 0000000,a96086a..9b09587 mode 000000,100644..100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@@ -1,0 -1,40 +1,39 @@@ + --- + title: Frequently Asked Questions + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + <a id="top"></a> + + # Frequently Asked Questions + + 1. [Why Does My Second Shade Include The Results Of The First Execution?](#two-executions) + + <a id="two-executions"></a> + + ### Why Does My Second Shade Include The Results Of The First Execution? + -By default, shade replaces with original jar with the result of shading. -So, when a `pom.xml` includes two shades, the second shade execution will -(by default) start from the result of the first shade execution. ++By default, shade replaces the original jar with the result of shading. ++So, when a `pom.xml` includes two shades, the second shade execution by default starts from the result of the first shade execution. + -If you're looking for two independent shades then read in -[shade:shade](shade-mojo.html) about ways choose a different name for your ++If you're looking for two independent shades, then read in ++[shade:shade](shade-mojo.html) about ways to choose a different name for your + first shade. diff --cc src/site/markdown/index.md index 0000000,787cf96..b047a99 mode 000000,100644..100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@@ -1,0 -1,53 +1,55 @@@ + --- + title: Introduction + author: + - Mauro Talevi + date: 2013-07-22 + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + # Apache Maven Shade Plugin -This plugin provides the capability to package the artifact in an uber-jar, including its dependencies and to _shade_ - i.e. rename - the packages of some of the dependencies. ++This plugin can package the artifact in an uber-jar, including its dependencies, and shade — that is, relocate — the packages of some of the dependencies. + + ## Goals Overview + -The Shade Plugin has a single goal: ++The Shade Plugin has 2 goals: + + - [shade:shade](./shade-mojo.html) is bound to the `package` phase and is used to create a shaded jar. ++- [shade:help](./help-mojo.html) displays help information about the plugin. ++ + ## Usage + + General instructions on how to use the Shade Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. + -In case you still have questions regarding the plugin's usage, please feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mail-lists.html). ++If you have questions regarding the plugin's usage, please feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). + -If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are we [...] ++If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcom [...] + + ## Examples + -To provide you with better understanding on some usages of the Shade Plugin, you can take a look into the following examples: ++To help you understand some usages of the Shade Plugin, look into the following examples: + + - [Selecting Contents for Uber JAR](./examples/includes-excludes.html) + - [Relocating Classes](./examples/class-relocation.html) + - [Merging Java Module Descriptors](./examples/module-info-merging.html) + - [Attaching the Shaded Artifact](./examples/attached-artifact.html) + - [Executable JAR](./examples/executable-jar.html) + - [Resource Transformers](./examples/resource-transformers.html) + - [Using another Shader implementation](./examples/use-shader-other-impl.html) diff --cc src/site/markdown/usage.md.vm index 0000000,24623b7..23d79e0 mode 000000,100644..100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@@ -1,0 -1,84 +1,87 @@@ + --- + title: Usage + author: + - Mauro Talevi + date: 2008-07-21 + --- + + <!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + + # Usage + + Creating a Shaded JAR + --------------------- + + The goals for the Shade Plugin are bound to the `package` phase in the build lifecycle. + + ```shell + mvn package + ``` + + Configuring Your Shade Plugin + ----------------------------- + + ```xml + <project> + ... + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-shade-plugin</artifactId> + <version>${currentVersion}</version> + <configuration> + <!-- put your configurations here --> + </configuration> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>shade</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> + </build> + ... + </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` ++|PropertiesTransformer|Merges properties files using an ordinal to resolve conflicts| ++|OpenWebBeansPropertiesTransformer|Merges Apache OpenWebBeans configuration files| ++|MicroprofileConfigTransformer|Merges Microprofile Config properties based on an ordinal| ++Transformers in `org.apache.maven.plugins.shade.resource` and `org.apache.maven.plugins.shade.resource.properties` + + For more information, see [samples](./examples/resource-transformers.html).
