shade:shade

Full name:

org.apache.maven.plugins:maven-shade-plugin:3.5.0:shade

Description:

Mojo that performs shading delegating to the Shader component.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: runtime.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: package.

Optional Parameters

Name Type Since Description
<artifactSet> ArtifactSet - Artifacts to include/exclude from the final artifact. Artifacts are denoted by composite identifiers of the general form groupId:artifactId:type:classifier. Since version 1.3, the wildcard characters '*' and '?' can be used within the sub parts of those composite identifiers to do pattern matching. For convenience, the syntax groupId is equivalent to groupId:*:*:*, groupId:artifactId is equivalent to groupId:artifactId:*:* and groupId:artifactId:classifier is equivalent to groupId:artifactId:*:classifier. For example: 
<artifactSet>
  <includes>
    <include>org.apache.maven:*</include>
  </includes>
  <excludes>
    <exclude>*:maven-core</exclude>
  </excludes>
</artifactSet>

<createDependencyReducedPom> boolean - Flag whether to generate a simplified POM for the shaded artifact. If set to true, dependencies that have been included into the uber JAR will be removed from the <dependencies> section of the generated POM. The reduced POM will be named dependency-reduced-pom.xml and is stored into the same directory as the shaded artifact. Unless you also specify dependencyReducedPomLocation, the plugin will create a temporary file named dependency-reduced-pom.xml in the project basedir.
Default value is: true.
<createSourcesJar> boolean - When true, it will attempt to create a sources jar as well
<createTestSourcesJar> boolean - When true, it will attempt to create a test sources jar.
<dependencyReducedPomLocation> File 1.7 Where to put the dependency reduced pom. Note: setting a value for this parameter with a directory other than ${basedir} will change the value of ${basedir} for all executions that come after the shade execution. This is often not what you want. This is considered an open issue with this plugin.
Default value is: ${basedir}/dependency-reduced-pom.xml.
<entryPoints> Set<String> 3.5.0 Use this option in order to fine-tune minimizeJar: By default, all of the target module's classes are kept and used as entry points for JAR minimization. By explicitly limiting the set of entry points, you can further minimize the set of classes kept in the shaded JAR. This affects both classes in the module itself and dependency classes. If minimizeJar is inactive, this option has no effect either.

Note: This feature requires Java 1.8 or higher due to its use of jdependency. Its accuracy therefore also depends on jdependency's limitations.

Configuration example:

<minimizeJar>true</minimizeJar>
<entryPoints>
  <entryPoint>org.acme.Application</entryPoint>
  <entryPoint>org.acme.OtherEntryPoint</entryPoint>
</entryPoints>

<filters> ArchiveFilter[] - Archive Filters to be used. Allows you to specify an artifact in the form of a composite identifier as used by artifactSet and a set of include/exclude file patterns for filtering which contents of the archive are added to the shaded jar. From a logical perspective, includes are processed before excludes, thus it's possible to use an include to collect a set of files from the archive then use excludes to further reduce the set. By default, all files are included and no files are excluded. If multiple filters apply to an artifact, the intersection of the matched files will be included in the final JAR. For example: 
<filters>
  <filter>
    <artifact>junit:junit</artifact>
    <includes>
      <include>org/junit/**</include>
    </includes>
    <excludes>
      <exclude>org/junit/experimental/**</exclude>
    </excludes>
  </filter>
</filters>

<finalName> String - The name of the shaded artifactId.

If you like to change the name of the native artifact, you may use the <build><finalName> setting. If this is set to something different than <build><finalName>, no file replacement will be performed, even if shadedArtifactAttached is being used.
<generateUniqueDependencyReducedPom> boolean 1.7.2 Create a dependency-reduced POM in ${basedir}/drp-UNIQUE.pom. This avoids build collisions of parallel builds without moving the dependency-reduced POM to a different directory. The property maven.shade.dependency-reduced-pom is set to the generated filename.
Default value is: false.
<keepDependenciesWithProvidedScope> boolean - When true, dependencies are kept in the pom but with scope 'provided'; when false, the dependency is removed.
<minimizeJar> boolean 1.4 When true, dependencies will be stripped down on the class level to only the transitive hull required for the artifact. See also entryPoints, if you wish to further optimize JAR minimization.

Note: This feature requires Java 1.8 or higher due to its use of jdependency. Its accuracy therefore also depends on jdependency's limitations.
<outputDirectory> File - The destination directory for the shaded artifact.
Default value is: ${project.build.directory}.
<outputFile> File 1.3 The path to the output file for the shaded artifact. When this parameter is set, the created archive will neither replace the project's main artifact nor will it be attached. Hence, this parameter causes the parameters finalName, shadedArtifactAttached, shadedClassifierName and createDependencyReducedPom to be ignored when used.
<promoteTransitiveDependencies> boolean - When true, transitive deps of removed dependencies are promoted to direct dependencies. This should allow the drop in replacement of the removed deps with the new shaded jar and everything should still work.
<relocations> PackageRelocation[] - Packages to be relocated. For example: 
<relocations>
  <relocation>
    <pattern>org.apache</pattern>
    <shadedPattern>hidden.org.apache</shadedPattern>
    <includes>
      <include>org.apache.maven.*</include>
    </includes>
    <excludes>
      <exclude>org.apache.maven.Public*</exclude>
    </excludes>
  </relocation>
</relocations>
Note: Support for includes exists only since version 1.4.
<shadedArtifactAttached> boolean - Defines whether the shaded artifact should be attached as classifier to the original artifact. If false, the shaded jar will be the main artifact of the project
<shadedArtifactId> String - The name of the shaded artifactId. So you may want to use a different artifactId and keep the standard version. If the original artifactId was "foo" then the final artifact would be something like foo-1.0.jar. So if you change the artifactId you might have something like foo-special-1.0.jar.
Default value is: ${project.artifactId}.
<shadedClassifierName> String - The name of the classifier used in case the shaded artifact is attached.
Default value is: shaded.
<shadedGroupFilter> String - If specified, this will include only artifacts which have groupIds which start with this.
<shaderHint> String 1.6 You can pass here the roleHint about your own Shader implementation plexus component.
<shadeSourcesContent> boolean - When true, it will attempt to shade the contents of Java source files when creating the sources JAR. When false, it will just relocate the Java source files to the shaded paths, but will not modify the actual source file contents.

Please note: This feature uses a heuristic search & replace approach which covers many, but definitely not all possible cases of source code shading and its excludes. There is no full Java parser behind this functionality, which would be the only way to get this right for Java language elements. As for matching within Java string constants, this is next to impossible to get 100% right, trying to guess if they are used in reflection or not.

Please understand that the source shading feature is not meant as a source code generator anyway, merely as a tool creating reasonably plausible source code when navigating to a relocated library class from an IDE, hopefully displaying source code which makes 95% sense - no more, no less.


Default value is: false.
User property is: shadeSourcesContent.
<shadeTestJar> boolean - When true, creates a shaded test-jar artifact as well.
Default value is: false.
<skip> boolean 3.3.0 When true, skips the execution of this MOJO.
Default value is: false.
<transformers> ResourceTransformer[] - Resource transformers to be used. Please see the "Examples" section for more information on available transformers and their configuration.
<useBaseVersion> boolean 3.0 When true, the version of each dependency of the reduced pom will be based on the baseVersion of the original dependency instead of its resolved version. For example, if the original pom (transitively) depends on a:a:2.7-SNAPSHOT, if useBaseVersion is set to false, the reduced pom will depend on a:a:2.7-20130312.222222-12 whereas if useBaseVersion is set to true, the reduced pom will depend on a:a:2.7-SNAPSHOT
Default value is: false.
<useDependencyReducedPomInJar> boolean 3.3.0 Add dependency reduced POM to the JAR instead of the original one provided by the project. If createDependencyReducedPom is false this parameter will be ignored.
Default value is: false.

Parameter Details

<artifactSet>

Artifacts to include/exclude from the final artifact. Artifacts are denoted by composite identifiers of the general form groupId:artifactId:type:classifier. Since version 1.3, the wildcard characters '*' and '?' can be used within the sub parts of those composite identifiers to do pattern matching. For convenience, the syntax groupId is equivalent to groupId:*:*:*, groupId:artifactId is equivalent to groupId:artifactId:*:* and groupId:artifactId:classifier is equivalent to groupId:artifactId:*:classifier. For example: 
<artifactSet>
  <includes>
    <include>org.apache.maven:*</include>
  </includes>
  <excludes>
    <exclude>*:maven-core</exclude>
  </excludes>
</artifactSet>

<createDependencyReducedPom>

Flag whether to generate a simplified POM for the shaded artifact. If set to true, dependencies that have been included into the uber JAR will be removed from the <dependencies> section of the generated POM. The reduced POM will be named dependency-reduced-pom.xml and is stored into the same directory as the shaded artifact. Unless you also specify dependencyReducedPomLocation, the plugin will create a temporary file named dependency-reduced-pom.xml in the project basedir.
  • Type: boolean
  • Required: No
  • Default: true

<createSourcesJar>

When true, it will attempt to create a sources jar as well
  • Type: boolean
  • Required: No

<createTestSourcesJar>

When true, it will attempt to create a test sources jar.
  • Type: boolean
  • Required: No

<dependencyReducedPomLocation>

Where to put the dependency reduced pom. Note: setting a value for this parameter with a directory other than ${basedir} will change the value of ${basedir} for all executions that come after the shade execution. This is often not what you want. This is considered an open issue with this plugin.
  • Type: java.io.File
  • Since: 1.7
  • Required: No
  • Default: ${basedir}/dependency-reduced-pom.xml

<entryPoints>

Use this option in order to fine-tune minimizeJar: By default, all of the target module's classes are kept and used as entry points for JAR minimization. By explicitly limiting the set of entry points, you can further minimize the set of classes kept in the shaded JAR. This affects both classes in the module itself and dependency classes. If minimizeJar is inactive, this option has no effect either.

Note: This feature requires Java 1.8 or higher due to its use of jdependency. Its accuracy therefore also depends on jdependency's limitations.

Configuration example:

<minimizeJar>true</minimizeJar>
<entryPoints>
  <entryPoint>org.acme.Application</entryPoint>
  <entryPoint>org.acme.OtherEntryPoint</entryPoint>
</entryPoints>
  • Type: java.util.Set<java.lang.String>
  • Since: 3.5.0
  • Required: No

<filters>

Archive Filters to be used. Allows you to specify an artifact in the form of a composite identifier as used by artifactSet and a set of include/exclude file patterns for filtering which contents of the archive are added to the shaded jar. From a logical perspective, includes are processed before excludes, thus it's possible to use an include to collect a set of files from the archive then use excludes to further reduce the set. By default, all files are included and no files are excluded. If multiple filters apply to an artifact, the intersection of the matched files will be included in the final JAR. For example: 
<filters>
  <filter>
    <artifact>junit:junit</artifact>
    <includes>
      <include>org/junit/**</include>
    </includes>
    <excludes>
      <exclude>org/junit/experimental/**</exclude>
    </excludes>
  </filter>
</filters>

<finalName>

The name of the shaded artifactId.

If you like to change the name of the native artifact, you may use the <build><finalName> setting. If this is set to something different than <build><finalName>, no file replacement will be performed, even if shadedArtifactAttached is being used.
  • Type: java.lang.String
  • Required: No

<generateUniqueDependencyReducedPom>

Create a dependency-reduced POM in ${basedir}/drp-UNIQUE.pom. This avoids build collisions of parallel builds without moving the dependency-reduced POM to a different directory. The property maven.shade.dependency-reduced-pom is set to the generated filename.
  • Type: boolean
  • Since: 1.7.2
  • Required: No
  • Default: false

<keepDependenciesWithProvidedScope>

When true, dependencies are kept in the pom but with scope 'provided'; when false, the dependency is removed.
  • Type: boolean
  • Required: No

<minimizeJar>

When true, dependencies will be stripped down on the class level to only the transitive hull required for the artifact. See also entryPoints, if you wish to further optimize JAR minimization.

Note: This feature requires Java 1.8 or higher due to its use of jdependency. Its accuracy therefore also depends on jdependency's limitations.

  • Type: boolean
  • Since: 1.4
  • Required: No

<outputDirectory>

The destination directory for the shaded artifact.
  • Type: java.io.File
  • Required: No
  • Default: ${project.build.directory}

<outputFile>

The path to the output file for the shaded artifact. When this parameter is set, the created archive will neither replace the project's main artifact nor will it be attached. Hence, this parameter causes the parameters finalName, shadedArtifactAttached, shadedClassifierName and createDependencyReducedPom to be ignored when used.
  • Type: java.io.File
  • Since: 1.3
  • Required: No

<promoteTransitiveDependencies>

When true, transitive deps of removed dependencies are promoted to direct dependencies. This should allow the drop in replacement of the removed deps with the new shaded jar and everything should still work.
  • Type: boolean
  • Required: No

<relocations>

Packages to be relocated. For example: 
<relocations>
  <relocation>
    <pattern>org.apache</pattern>
    <shadedPattern>hidden.org.apache</shadedPattern>
    <includes>
      <include>org.apache.maven.*</include>
    </includes>
    <excludes>
      <exclude>org.apache.maven.Public*</exclude>
    </excludes>
  </relocation>
</relocations>
Note: Support for includes exists only since version 1.4.

<shadedArtifactAttached>

Defines whether the shaded artifact should be attached as classifier to the original artifact. If false, the shaded jar will be the main artifact of the project
  • Type: boolean
  • Required: No

<shadedArtifactId>

The name of the shaded artifactId. So you may want to use a different artifactId and keep the standard version. If the original artifactId was "foo" then the final artifact would be something like foo-1.0.jar. So if you change the artifactId you might have something like foo-special-1.0.jar.
  • Type: java.lang.String
  • Required: No
  • Default: ${project.artifactId}

<shadedClassifierName>

The name of the classifier used in case the shaded artifact is attached.
  • Type: java.lang.String
  • Required: No
  • Default: shaded

<shadedGroupFilter>

If specified, this will include only artifacts which have groupIds which start with this.
  • Type: java.lang.String
  • Required: No

<shaderHint>

You can pass here the roleHint about your own Shader implementation plexus component.
  • Type: java.lang.String
  • Since: 1.6
  • Required: No

<shadeSourcesContent>

When true, it will attempt to shade the contents of Java source files when creating the sources JAR. When false, it will just relocate the Java source files to the shaded paths, but will not modify the actual source file contents.

Please note: This feature uses a heuristic search & replace approach which covers many, but definitely not all possible cases of source code shading and its excludes. There is no full Java parser behind this functionality, which would be the only way to get this right for Java language elements. As for matching within Java string constants, this is next to impossible to get 100% right, trying to guess if they are used in reflection or not.

Please understand that the source shading feature is not meant as a source code generator anyway, merely as a tool creating reasonably plausible source code when navigating to a relocated library class from an IDE, hopefully displaying source code which makes 95% sense - no more, no less.

  • Type: boolean
  • Required: No
  • User Property: shadeSourcesContent
  • Default: false

<shadeTestJar>

When true, creates a shaded test-jar artifact as well.
  • Type: boolean
  • Required: No
  • Default: false

<skip>

When true, skips the execution of this MOJO.
  • Type: boolean
  • Since: 3.3.0
  • Required: No
  • Default: false

<transformers>

Resource transformers to be used. Please see the "Examples" section for more information on available transformers and their configuration.

<useBaseVersion>

When true, the version of each dependency of the reduced pom will be based on the baseVersion of the original dependency instead of its resolved version. For example, if the original pom (transitively) depends on a:a:2.7-SNAPSHOT, if useBaseVersion is set to false, the reduced pom will depend on a:a:2.7-20130312.222222-12 whereas if useBaseVersion is set to true, the reduced pom will depend on a:a:2.7-SNAPSHOT
  • Type: boolean
  • Since: 3.0
  • Required: No
  • Default: false

<useDependencyReducedPomInJar>

Add dependency reduced POM to the JAR instead of the original one provided by the project. If createDependencyReducedPom is false this parameter will be ignored.
  • Type: boolean
  • Since: 3.3.0
  • Required: No
  • Default: false