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.
107 lines
3.9 KiB
Plaintext
107 lines
3.9 KiB
Plaintext
== Configuring Shadow
|
|
|
|
The link:{api}/tasks/ShadowJar.html[`ShadowJar`] task type extends from Gradle's
|
|
https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html[`Jar`] type.
|
|
This means that all attributes and methods available on `Jar` are also available on
|
|
link:{api}/tasks/ShadowJar.html[`ShadowJar`].
|
|
Refer the __Gradle User Guide__ for https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html[Jar] for
|
|
details.
|
|
|
|
=== Configuring Output Name
|
|
|
|
Shadow configures the default `shadowJar` task to set the output JAR's `destinationDir`, `baseName`, `appendix`,
|
|
`version`, and `extension` to the same default values as Gradle does for all `Jar` tasks.
|
|
Additionally, it configures the `classifier` to be `all`.
|
|
|
|
If working with a Gradle project with the name `myApp` and version `1.0`, the default `shadowJar` task will output a
|
|
file at: `build/libs/myApp-1.0-all.jar`
|
|
|
|
As with all `Jar` tasks in Gradle, these values can be overridden:
|
|
|
|
.Output to `build/libs/shadow.jar`
|
|
[source,groovy,indent=0]
|
|
----
|
|
include::{tests}/ShadowPluginSpec.groovy[tags=rename]
|
|
----
|
|
|
|
=== Configuring the Runtime Classpath
|
|
|
|
Each Java JAR file contains a manifest file that provides meta data about the contents of the JAR file itself.
|
|
When using a shadowed JAR file as an executable JAR, it is assumed that all necessary runtime classes are contained
|
|
within the JAR itself.
|
|
There may be situations where the desire is to **not** bundle select dependencies into the shadowed JAR file but
|
|
they are still required for runtime execution.
|
|
|
|
In these scenarios, Shadow creates a `shadow` configuration to declare these dependencies.
|
|
Dependencies added to the `shadow` configuration are *not* bundled into the output JAR.
|
|
Think of `configurations.shadow` as unmerged, runtime dependencies.
|
|
The integration with the `maven` and `maven-publish` plugins will automatically configure dependencies added
|
|
to `configurations.shadow` as `RUNTIME` scope dependencies in the resulting POM file.
|
|
|
|
Additionally, Shadow automatically configures the manifest of the `shadowJar` task to contain a `Class-Path` entry
|
|
in the JAR manifest.
|
|
The value of the `Class-Path` entry is the name of all dependencies resolved in the `shadow` configuration
|
|
for the project.
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
include::{tests}/ShadowPluginSpec.groovy[tags=shadowConfig]
|
|
----
|
|
|
|
Inspecting the `META-INF/MANIFEST.MF` entry in the JAR file will reveal the following attribute:
|
|
[source,property,indent=0]
|
|
----
|
|
Class-Path: junit-3.8.2.jar
|
|
----
|
|
|
|
When deploying a shadowed JAR as an execution JAR, it is important to note that any non-bundled runtime dependencies
|
|
**must** be deployed in the location specified in the `Class-Path` entry in the manifest.
|
|
|
|
=== Configuring the JAR Manifest
|
|
|
|
Beyond the automatic configuration of the `Class-Path` entry, the `shadowJar` manifest is configured in a number of ways.
|
|
First, the manifest for the `shadowJar` task is configured to __inherit__ from the manifest of the standard `jar` task.
|
|
This means that any configuration performed on the `jar` task will propagate to the `shadowJar` tasks.
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
include::{tests}/ShadowPluginSpec.groovy[tags=jarManifest]
|
|
----
|
|
|
|
Inspecting the `META-INF/MANIFEST.MF` entry in the JAR file will revel the following attribute:
|
|
[source,property,indent=0]
|
|
----
|
|
Class-Path: /libs/a.jar
|
|
----
|
|
|
|
If it is desired to inherit a manifest from a JAR task other than the standard `jar` task, the `inheritFrom` methods
|
|
on the `shadowJar.manifest` object can be used to configure the upstream.
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
|
|
task testJar(type: Jar) {
|
|
manifest {
|
|
attributes 'Description': 'This is an application JAR'
|
|
}
|
|
}
|
|
|
|
shadowJar {
|
|
manifest {
|
|
inheritFrom project.tasks.testJar.manifest
|
|
}
|
|
}
|
|
----
|
|
|
|
include::11-filtering-contents.adoc[]
|
|
|
|
include::12-controlling-dependencies.adoc[]
|
|
|
|
include::13-controlling-merging.adoc[]
|
|
|
|
include::14-package-relocation.adoc[]
|
|
|
|
include::15-minimizing.adoc[]
|
|
|
|
include::16-reproducible-builds.adoc[]
|