You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 lines
2.9 KiB
Plaintext
73 lines
2.9 KiB
Plaintext
=== Relocating Packages
|
|
|
|
Shade is capable of scanning a project's classes and relocating specific dependencies to a new location.
|
|
This is often required when one of the dependencies is susceptible to breaking changes in versions or
|
|
to classpath pollution in a downstream project.
|
|
|
|
[NOTE]
|
|
====
|
|
Google's Guava and the ASM library are typical cases where package relocation can come in handy.
|
|
====
|
|
|
|
Shadow uses the ASM library to modify class byte code to replace the package name and any import
|
|
statements for a class.
|
|
Any non-class files that are stored within a package structure are also relocated to the new location.
|
|
|
|
.Relocating a Package
|
|
[source,groovy,indent=0]
|
|
----
|
|
include::{tests}/RelocationSpec.groovy[tags=relocate]
|
|
----
|
|
|
|
The code snippet will rewrite the location for any class in the `junit.framework` to be `shadow.junit`.
|
|
For example, the class `junit.textui.TestRunner` becomes `shadow.junit.TestRunner`.
|
|
In the resulting JAR, the class file is relocated from `junit/textui/TestRunner.class` to
|
|
`shadow/junit/TestRunner.class`.
|
|
|
|
[NOTE]
|
|
====
|
|
Relocation operates at a package level.
|
|
It is not necessary to specify any patterns for matching, it will operate simply on the prefix
|
|
provided.
|
|
====
|
|
|
|
[NOTE]
|
|
====
|
|
Relocation will be applied globally to all instance of the matched prefix.
|
|
That is, it does **not** scope to __only__ the dependencies being shadowed.
|
|
Be specific as possible when configuring relocation as to avoid unintended relocations.
|
|
====
|
|
|
|
==== Filtering Relocation
|
|
|
|
Specific classes or files can be `included`/`excluded` from the relocation operation if necessary.
|
|
|
|
.Configuring Filtering for Relocation
|
|
[source,groovy,indent=0]
|
|
----
|
|
include::{tests}/RelocationSpec.groovy[tags=relocateFilter]
|
|
----
|
|
|
|
==== Automatically Relocating Dependencies
|
|
Shadow ships with a task that can be used to automatically configure all packages from all dependencies to be relocated.
|
|
To configure automatic dependency relocation, declare a task of type `ConfigureShadowRelocation` and configure the
|
|
`target` parameter to be the `ShadowJar` task you wish to auto configure. You will also need to declared a task
|
|
dependency so the tasks execute in the correct order.
|
|
.Configure Auto Relocation
|
|
[source,groovy]
|
|
----
|
|
task relocateShadowJar(type: ConfigureShadowRelocation) {
|
|
target = tasks.shadowJar
|
|
prefix = "myapp" // Default value is "shadow"
|
|
}
|
|
tasks.shadowJar.dependsOn tasks.relocateShadowJar
|
|
----
|
|
[NOTE]
|
|
====
|
|
Configuring package auto relocation can add significant time to the shadow process as it will process all dependencies
|
|
in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations.
|
|
Be mindful that some Gradle plugins (such as `java-gradle-plugin` will automatically add dependencies to your class path
|
|
(e.g. `java-gradle-plugin` automatically adds the full Gradle API to your `compile` configuratinon. You may need to
|
|
remove these dependencies if you do not intend to shadow them into your library.
|
|
====
|