diff --git a/README.md b/README.md index ea19cf38b..548e558a7 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,5 @@ Gradle plugin for creating fat/uber JARs with support for package relocation. | 9.3.0+ | 9.0 | 17 | [`com.gradleup.shadow`][gradleup's] | | 9.5.0+ | 9.2 | 17 | [`com.gradleup.shadow`][gradleup's] | - - [johnrengelman's]: https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow [gradleup's]: https://plugins.gradle.org/plugin/com.gradleup.shadow diff --git a/docs/README.md b/docs/README.md index d6d67e44a..e82e0d8d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,10 +4,10 @@ # Introduction -Shadow is a Gradle plugin for combining a project's dependency classes and resources into a single -output Jar. The combined Jar is often referred to a _fat-jar_ or _uber-jar_. -Shadow utilizes [`JarInputStream`][JarInputStream] and [`JarOutputStream`][JarOutputStream] to efficiently process -dependent libraries into the output jar without incurring the I/O overhead of expanding the jars to disk. +Shadow is a Gradle plugin for combining a project's dependency classes and resources into a single output Jar. The +combined Jar is often referred to a _fat-jar_ or _uber-jar_. Shadow utilizes [`JarInputStream`][JarInputStream] and [ +`JarOutputStream`][JarOutputStream] to efficiently process dependent libraries into the output jar without incurring the +I/O overhead of expanding the jars to disk. !!! warning "Plugin ID Change" @@ -39,15 +39,12 @@ Shadowing a project output has 2 major use cases: ### Executable Distributions Executable distribution is the main use case for deploying an _application_ that can be executed/run in the runtime -environment. -In the case of Shadow, this is a single _uber_ or _fat_ JAR. -The JAR file contains all the application code and dependent libraries to execute (not including the standard JVM -libraries). -The shadow JAR does **not** include the JRE itself. -It must be available on the target system. +environment. In the case of Shadow, this is a single _uber_ or _fat_ JAR. The JAR file contains all the application code +and dependent libraries to execute (not including the standard JVM libraries). The shadow JAR does **not** include the +JRE itself. It must be available on the target system. -Executable JARs contain a JAR MANIFEST that specifies the application Main Class. -This allows the application to be started with a single command: +Executable JARs contain a JAR MANIFEST that specifies the application Main Class. This allows the application to be +started with a single command: ```sh java -jar application-shadow.jar @@ -55,18 +52,16 @@ java -jar application-shadow.jar ### Library Bundling -Dependency bundling and relocation is the main use case for _library_ authors. -The goal of a bundled library is to create a pre-packaged dependency for other libraries or applications to utilize. -Often in these scenarios, a library may contain a dependency that a downstream library or application also uses. -In _some_ cases, different versions of this common dependency can cause an issue in either the upstream library or -the downstream application. -These issues often manifest themselves as binary incompatibilities in either the library or application code. +Dependency bundling and relocation is the main use case for _library_ authors. The goal of a bundled library is to +create a pre-packaged dependency for other libraries or applications to utilize. Often in these scenarios, a library may +contain a dependency that a downstream library or application also uses. In _some_ cases, different versions of this +common dependency can cause an issue in either the upstream library or the downstream application. These issues often +manifest themselves as binary incompatibilities in either the library or application code. By utilizing Shadow's ability to _relocate_ the package names for dependencies, a library author can ensure that the library's dependencies will not conflict with the same dependency being declared by the downstream application. - [JarInputStream]: https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarInputStream.html [JarOutputStream]: https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarOutputStream.html [johnrengelman's]: https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow diff --git a/docs/about/README.md b/docs/about/README.md index bfc545d22..7a9aa6491 100644 --- a/docs/about/README.md +++ b/docs/about/README.md @@ -1,20 +1,16 @@ # About This Project I (John Engelman) started this project in December 2012. We were working on converting from a monolithic application -into the new hot jazz of "microservices" using Dropwizard. -I had also just started learning about Gradle and I knew that the incremental build system it provided would benefit -our development team greatly. -Unfortunately, the closest thing that Gradle had to Maven's Shade plugin was its ability to create application TARs and -ZIPs. +into the new hot jazz of "microservices" using Dropwizard. I had also just started learning about Gradle and I knew that +the incremental build system it provided would benefit our development team greatly. Unfortunately, the closest thing +that Gradle had to Maven's Shade plugin was its ability to create application TARs and ZIPs. -So, Charlie Knudsen and I set out to port the existing Shade code into a Gradle plugin. -This port is what existed up until the `0.9` milestone releases for Shadow. -It functioned, but it wasn't idiomatic Gradle by any means. +So, Charlie Knudsen and I set out to port the existing Shade code into a Gradle plugin. This port is what existed up +until the `0.9` milestone releases for Shadow. It functioned, but it wasn't idiomatic Gradle by any means. Starting with 0.9, Shadow was rewritten from the ground up as standard Gradle plugin and leveraged as much of Gradle's -classes and concepts as possible. -At the same time as the 0.9 release, Gradle was announcing the [Gradle Plugin Portal](https://plugins.gradle.org) and -so Shadow was published there. +classes and concepts as possible. At the same time as the 0.9 release, Gradle was announcing +the [Gradle Plugin Portal](https://plugins.gradle.org) and so Shadow was published there. ## Maintainers diff --git a/docs/application-plugin/README.md b/docs/application-plugin/README.md index 6d7fabf85..c63aa0d0f 100644 --- a/docs/application-plugin/README.md +++ b/docs/application-plugin/README.md @@ -3,9 +3,9 @@ Shadow reacts to the presence of Gradle's [`application`][application] plugin and will automatically configure additional tasks for running the shadowed JAR and creating distributions containing the shadowed JAR. -Just like the normal [`Jar`][Jar] task, when the [`application`][application] plugin is applied, -the [`ShadowJar`][ShadowJar] manifest will be configured to contain the `Main-Class` attribute with the value specified -in the project's `application.mainClass` attribute. +Just like the normal [`Jar`][Jar] task, when the [`application`][application] plugin is applied, the [ +`ShadowJar`][ShadowJar] manifest will be configured to contain the `Main-Class` attribute with the value specified in +the project's `application.mainClass` attribute. === "Kotlin" @@ -35,10 +35,9 @@ in the project's `application.mainClass` attribute. ## Running the Shadow JAR -When applied along with the `application` plugin, the `runShadow` task will be created for starting -the application from the shadowed JAR. -The `runShadow` task is a [`JavaExec`][JavaExec] task that is configured to execute `java -jar myproject-all.jar`. -It can be configured the same as any other [`JavaExec`][JavaExec] task. +When applied along with the `application` plugin, the `runShadow` task will be created for starting the application from +the shadowed JAR. The `runShadow` task is a [`JavaExec`][JavaExec] task that is configured to execute +`java -jar myproject-all.jar`. It can be configured the same as any other [`JavaExec`][JavaExec] task. === "Kotlin" @@ -81,9 +80,8 @@ It can be configured the same as any other [`JavaExec`][JavaExec] task. ## Distributing the Shadow JAR The Shadow plugin will also configure distribution tasks when in the presence of the [`application`][application] -plugin. The plugin will create `shadowDistZip` and `shadowDistTar` which creates Zip and Tar distributions -respectively. Each distribution will contain the shadowed JAR file along with the necessary start scripts to launch -the application. +plugin. The plugin will create `shadowDistZip` and `shadowDistTar` which creates Zip and Tar distributions respectively. +Each distribution will contain the shadowed JAR file along with the necessary start scripts to launch the application. Additionally, the plugin will create the `installShadowDist` and `startShadowScripts` tasks which stages the necessary files for a distribution to `build/install/-shadow/`. @@ -170,7 +168,6 @@ View [The Distribution Plugin](https://docs.gradle.org/current/userguide/distrib for more information about configuring distributions. - [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html [JavaExec]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html [ShadowJar]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/index.html diff --git a/docs/configuration/README.md b/docs/configuration/README.md index 06770b18e..219404e0b 100644 --- a/docs/configuration/README.md +++ b/docs/configuration/README.md @@ -1,7 +1,7 @@ # Configuring Shadow -The [`ShadowJar`][ShadowJar] task type extends from Gradle's [`Jar`][Jar] type. -This means that all attributes and methods available on [`Jar`][Jar] are also available on [`ShadowJar`][ShadowJar]. +The [`ShadowJar`][ShadowJar] task type extends from Gradle's [`Jar`][Jar] type. This means that all attributes and +methods available on [`Jar`][Jar] are also available on [`ShadowJar`][ShadowJar]. ## Configuring Output Name @@ -47,22 +47,19 @@ This will result in the output file being named `myApp-all.jar` instead of `myAp ## Configuring the Runtime Classpath -Each Java JAR file contains a manifest file that provides metadata 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. +Each Java JAR file contains a manifest file that provides metadata 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-publish`][maven-publish] plugin will automatically configure dependencies added -to `configurations.shadow` as `RUNTIME` scope dependencies in the resulting POM file. +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-publish`][maven-publish] plugin 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`][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. +`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. === "Kotlin" @@ -91,8 +88,8 @@ When deploying a shadowed JAR as an execution JAR, it is important to note that ## Configuring the JAR Manifest -The [`ShadowJar`][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. +The [`ShadowJar`][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. === "Kotlin" @@ -153,8 +150,8 @@ configure the upstream. ## Adding Multi-Release Manifest Attribute -The [`ShadowJar`][ShadowJar] task can automatically add the `Multi-Release` attribute to the JAR manifest if any of -the included dependencies contain this attribute. This is controlled by the `addMultiReleaseAttribute` property. +The [`ShadowJar`][ShadowJar] task can automatically add the `Multi-Release` attribute to the JAR manifest if any of the +included dependencies contain this attribute. This is controlled by the `addMultiReleaseAttribute` property. By default, `addMultiReleaseAttribute` is set to `true`. When enabled, Shadow will scan all dependencies being merged into the shadow JAR. If any dependency JAR has the `Multi-Release` manifest attribute set to `true`, Shadow will add @@ -178,8 +175,8 @@ You can disable this behavior by setting `addMultiReleaseAttribute` to `false`: } ``` -This is useful if you want to control the presence of the `Multi-Release` attribute manually or avoid inheriting it -from dependencies. +This is useful if you want to control the presence of the `Multi-Release` attribute manually or avoid inheriting it from +dependencies. ## Adding Extra Files @@ -208,7 +205,8 @@ method can be used to add extra files. } ``` -See also [Embedding Local Jar Files Into Your Shadowed Jar](dependencies/README.md#embedding-local-jar-files-into-your-shadowed-jar). +See +also [Embedding Local Jar Files Into Your Shadowed Jar](dependencies/README.md#embedding-local-jar-files-into-your-shadowed-jar). [Jar.from]: https://docs.gradle.org/current/dsl/org.gradle.jvm.tasks.Jar.html#org.gradle.jvm.tasks.Jar:from(java.lang.Object,%20org.gradle.api.Action) diff --git a/docs/configuration/dependencies/README.md b/docs/configuration/dependencies/README.md index b7a87f6b3..58262214c 100644 --- a/docs/configuration/dependencies/README.md +++ b/docs/configuration/dependencies/README.md @@ -22,8 +22,8 @@ merging can be configured using the [`configurations`][ShadowJar.configurations] ``` The above code sample would configure the [`ShadowJar`][ShadowJar] task to merge dependencies from only the -`compileClasspath` configuration. -This means any dependency declared in the `runtimeOnly` configuration would be **not** be included in the final JAR. +`compileClasspath` configuration. This means any dependency declared in the `runtimeOnly` configuration would be **not** +be included in the final JAR. > Note the literal use of [`project.configurations`][Project.configurations] when setting the > [`configurations`][ShadowJar.configurations] attribute of a [`ShadowJar`][ShadowJar] task. @@ -99,9 +99,9 @@ See also [Adding Extra Files](../README.md#adding-extra-files) Dependencies added into `runtimeClasspath` configuration (`api`, `implementation`, `runtimeOnly`) will be unzipped and merged into the shadowed JAR. Not all dependencies are JAR files, e.g. some of them are [POM files](https://repo1.maven.org/maven2/org/graalvm/polyglot/js-community/24.2.2/), -[SO files](https://repo1.maven.org/maven2/io/github/ganadist/sqlite4java/libsqlite4java-osx-aarch64/1.0.392/), -and so on. If such dependencies are added into `runtimeClasspath`, you will encounter the following error when building -the shadowed JAR: +[SO files](https://repo1.maven.org/maven2/io/github/ganadist/sqlite4java/libsqlite4java-osx-aarch64/1.0.392/), and so +on. If such dependencies are added into `runtimeClasspath`, you will encounter the following error when building the +shadowed JAR: ``` * What went wrong: @@ -168,8 +168,8 @@ configuration. ### Excluding Non-JAR Transitive Dependencies -If the non-JAR file is a transitive dependency (e.g., a POM-only metapackage) that you don't actually need -in your shadowed JAR, you can exclude it using the `dependencies` block instead of embedding it. +If the non-JAR file is a transitive dependency (e.g., a POM-only metapackage) that you don't actually need in your +shadowed JAR, you can exclude it using the `dependencies` block instead of embedding it. === "Kotlin" @@ -200,8 +200,8 @@ in your shadowed JAR, you can exclude it using the `dependencies` block instead ## Filtering Dependencies Individual dependencies can be filtered from the final JAR by using the `dependencies` block of a -[`ShadowJar`][ShadowJar] task. Dependency filtering does **not** apply to transitive dependencies. -That is, excluding a dependency does not exclude any of its dependencies from the final JAR. +[`ShadowJar`][ShadowJar] task. Dependency filtering does **not** apply to transitive dependencies. That is, excluding a +dependency does not exclude any of its dependencies from the final JAR. The `dependency` blocks provides a number of methods for resolving dependencies using the notations familiar from Gradle's [`project.configurations`][Project.configurations] block. @@ -268,9 +268,8 @@ Gradle's [`project.configurations`][Project.configurations] block. ### Using Regex Patterns to Filter Dependencies -Dependencies can be filtered using regex patterns. -Coupled with the `::` notation for dependencies, this allows for excluding/including -using any of these individual fields. +Dependencies can be filtered using regex patterns. Coupled with the `::` notation for +dependencies, this allows for excluding/including using any of these individual fields. === "Kotlin" @@ -475,8 +474,6 @@ block provides a method that accepts a `Closure` for selecting dependencies. } ``` - - [Jar.from]: https://docs.gradle.org/current/dsl/org.gradle.jvm.tasks.Jar.html#org.gradle.jvm.tasks.Jar:from(java.lang.Object,%20org.gradle.api.Action) [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html [ShadowJar.configurations]: ../../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/configurations.html diff --git a/docs/configuration/filtering/README.md b/docs/configuration/filtering/README.md index e60e10937..e1e04eab1 100644 --- a/docs/configuration/filtering/README.md +++ b/docs/configuration/filtering/README.md @@ -3,9 +3,9 @@ The final contents of a shadow JAR can be filtered using the `exclude` and `include` methods inherited from Gradle's [`Jar`][Jar] task type. -When using `exclude`/`include` with a [`ShadowJar`][ShadowJar] task, the resulting copy specs are applied to the -_final_ JAR contents. This means that, the configuration is applied to the individual files from both the project -source set or _any_ of the dependencies to be merged. +When using `exclude`/`include` with a [`ShadowJar`][ShadowJar] task, the resulting copy specs are applied to the _final_ +JAR contents. This means that, the configuration is applied to the individual files from both the project source set or +_any_ of the dependencies to be merged. === "Kotlin" @@ -46,7 +46,5 @@ Excludes and includes can be combined just like a normal [`Jar`][Jar] task, with } ``` - - [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html [ShadowJar]: ../../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/index.html diff --git a/docs/configuration/merging/README.md b/docs/configuration/merging/README.md index ae62f31b9..bd0bde2fc 100644 --- a/docs/configuration/merging/README.md +++ b/docs/configuration/merging/README.md @@ -9,7 +9,8 @@ should process a particular entry and apply any modifications before writing the **Important**: [`ResourceTransformer`][ResourceTransformer] follows a guaranteed processing order: 1. **Project files first**: All files in projects are processed before any dependency files. -2. **Dependency files second**: Files from configurations (runtime dependencies) or added via [`ShadowJar.from`][ShadowJar.from] are processed after project files. +2. **Dependency files second**: Files from configurations (runtime dependencies) or added via [ + `ShadowJar.from`][ShadowJar.from] are processed after project files. This ordering is crucial when merging configuration files where you want to preserve project-specific values while merging in additional data from dependencies. @@ -86,24 +87,25 @@ steps to take: 1. Set the default strategy to `INCLUDE` or `WARN`. 2. Apply your [`ResourceTransformer`][ResourceTransformer]s. 3. Remove duplicate entries by - - overriding the default strategy for specific files to `EXCLUDE` or `FAIL` using - [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], or [`eachFile`][Jar.eachFile] functions - - or applying [`PreserveFirstFoundResourceTransformer`][PreserveFirstFoundResourceTransformer] for specific files - - or write your own [`ResourceTransformer`][ResourceTransformer] to handle duplicates - - or mechanism similar. + - overriding the default strategy for specific files to `EXCLUDE` or `FAIL` using + [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], or [`eachFile`][Jar.eachFile] + functions + - or applying [`PreserveFirstFoundResourceTransformer`][PreserveFirstFoundResourceTransformer] for specific files + - or write your own [`ResourceTransformer`][ResourceTransformer] to handle duplicates + - or mechanism similar. Alternatively, you can follow these steps: 1. Set the default strategy to `EXCLUDE` or `FAIL`. 2. Apply your [`ResourceTransformer`][ResourceTransformer]s. 3. Bypass the duplicate entries which should be handled by the [`ResourceTransformer`][ResourceTransformer]s using - [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], or [`eachFile`][Jar.eachFile] functions - to set their `duplicatesStrategy` to `INCLUDE` or `WARN`. + [`filesMatching`][Jar.filesMatching], [`filesNotMatching`][Jar.filesNotMatching], or [`eachFile`][Jar.eachFile] + functions to set their `duplicatesStrategy` to `INCLUDE` or `WARN`. Optional steps: -- Enable [`ShadowJar.failOnDuplicateEntries`][ShadowJar.failOnDuplicateEntries] to check duplicate entries in the final JAR. - This can also ensure the regressions are caught in the future. +- Enable [`ShadowJar.failOnDuplicateEntries`][ShadowJar.failOnDuplicateEntries] to check duplicate entries in the final + JAR. This can also ensure the regressions are caught in the future. - Use [Diffuse](https://github.com/JakeWharton/diffuse) to diff the JARs. Here are some examples: @@ -298,16 +300,16 @@ can also be provided. ## Merging Service Descriptor Files -Java libraries often contain service descriptors files in the `META-INF/services` directory of the JAR. -A service descriptor typically contains a line delimited list of classes that are supported for a particular _service_. -At runtime, this file is read and used to configure library or application behavior. +Java libraries often contain service descriptors files in the `META-INF/services` directory of the JAR. A service +descriptor typically contains a line delimited list of classes that are supported for a particular _service_. At +runtime, this file is read and used to configure library or application behavior. -Multiple dependencies may use the same service descriptor file name. -In this case, it is generally desired to merge the content of each instance of the file into a single output file. -The [`ServiceFileTransformer`][ServiceFileTransformer] class is used to perform this merging. -By default, it will merge each copy of a file under `META-INF/services` into a single file in the output JAR. -You can use either the short syntax method [`mergeServiceFiles()`][ShadowJar.mergeServiceFiles] or the full syntax -method [`transform`][ShadowJar.transform] to add the [`ServiceFileTransformer`][ServiceFileTransformer]: +Multiple dependencies may use the same service descriptor file name. In this case, it is generally desired to merge the +content of each instance of the file into a single output file. The [`ServiceFileTransformer`][ServiceFileTransformer] +class is used to perform this merging. By default, it will merge each copy of a file under `META-INF/services` into a +single file in the output JAR. You can use either the short syntax method [ +`mergeServiceFiles()`][ShadowJar.mergeServiceFiles] or the full syntax method [`transform`][ShadowJar.transform] to add +the [`ServiceFileTransformer`][ServiceFileTransformer]: === "Kotlin" @@ -415,10 +417,10 @@ from merging. ## Merging Groovy Extension Modules -Shadow provides a specific transformer for dealing with Groovy extension module files. -This is due to their special syntax and how they need to be merged together. -The [`GroovyExtensionModuleTransformer`][GroovyExtensionModuleTransformer] will handle these files. -The [`ShadowJar`][ShadowJar] task also provides a short syntax method to add this transformer. +Shadow provides a specific transformer for dealing with Groovy extension module files. This is due to their special +syntax and how they need to be merged together. The [ +`GroovyExtensionModuleTransformer`][GroovyExtensionModuleTransformer] will handle these files. The [ +`ShadowJar`][ShadowJar] task also provides a short syntax method to add this transformer. === "Kotlin" @@ -448,8 +450,8 @@ The [`ShadowJar`][ShadowJar] task also provides a short syntax method to add thi [`Log4j2PluginsCacheFileTransformer`][Log4j2PluginsCacheFileTransformer] is a [`ResourceTransformer`][ResourceTransformer] that merges -`META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat` plugin caches from all the jars -containing Log4j 2.x Core components. It's a Gradle equivalent of +`META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat` plugin caches from all the jars containing +Log4j 2.x Core components. It's a Gradle equivalent of [Log4j Plugin Descriptor Transformer](https://logging.apache.org/log4j/transform/log4j-transform-maven-shade-plugin-extensions.html#log4j-plugin-cache-transformer). === "Kotlin" @@ -470,10 +472,9 @@ containing Log4j 2.x Core components. It's a Gradle equivalent of ## Appending Text Files -Generic text files can be appended together using the [`AppendingTransformer`][AppendingTransformer]. -Each file is appended using separators (defaults to `\n`) to separate content. -The [`ShadowJar`][ShadowJar] task provides a short syntax method of [`append(String)`][ShadowJar.append] to configure -this transformer. +Generic text files can be appended together using the [`AppendingTransformer`][AppendingTransformer]. Each file is +appended using separators (defaults to `\n`) to separate content. The [`ShadowJar`][ShadowJar] task provides a short +syntax method of [`append(String)`][ShadowJar.append] to configure this transformer. === "Kotlin" @@ -522,9 +523,9 @@ this transformer. ## Appending XML Files XML files require a special transformer for merging. The [`XmlAppendingTransformer`][XmlAppendingTransformer] -reads each XML document and merges each root element into a single document. -There is no short syntax method for the [`XmlAppendingTransformer`][XmlAppendingTransformer]. -It must be added using the [`transform`][ShadowJar.transform] methods. +reads each XML document and merges each root element into a single document. There is no short syntax method for the [ +`XmlAppendingTransformer`][XmlAppendingTransformer]. It must be added using the [`transform`][ShadowJar.transform] +methods. === "Kotlin" @@ -584,10 +585,11 @@ You can use `include`/`exclude` and more methods to configure the patterns for t ## Finding Resources in the Classpath -When dealing with resource merge conflicts, it can be helpful to find which dependencies contain the conflicting resources. -Shadow provides a [`FindResourceInClasspath`][FindResourceInClasspath] helper task for this purpose. +When dealing with resource merge conflicts, it can be helpful to find which dependencies contain the conflicting +resources. Shadow provides a [`FindResourceInClasspath`][FindResourceInClasspath] helper task for this purpose. -To scan for resources, register a [`FindResourceInClasspath`][FindResourceInClasspath] task in your build script and configure its `classpath` and the resource patterns to look for: +To scan for resources, register a [`FindResourceInClasspath`][FindResourceInClasspath] task in your build script and +configure its `classpath` and the resource patterns to look for: === "Kotlin" @@ -613,8 +615,6 @@ You can then run the task to scan each entry on the classpath and print any matc ./gradlew findResources ``` - - [AbstractCopyTask]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.AbstractCopyTask.html [Jar.eachFile]: https://docs.gradle.org/current/dsl/org.gradle.jvm.tasks.Jar.html#org.gradle.jvm.tasks.Jar:eachFile(org.gradle.api.Action) [Jar.filesMatching]: https://docs.gradle.org/current/dsl/org.gradle.jvm.tasks.Jar.html#org.gradle.jvm.tasks.Jar:filesMatching(java.lang.Iterable,%20org.gradle.api.Action) diff --git a/docs/configuration/minimizing/README.md b/docs/configuration/minimizing/README.md index 91ab66b5d..15b5169f0 100644 --- a/docs/configuration/minimizing/README.md +++ b/docs/configuration/minimizing/README.md @@ -19,10 +19,10 @@ minimizing the resulting shadowed JAR. } ``` -A dependency can be excluded from the minimization process, thereby forcing its inclusion the shadow JAR. -This is useful when the dependency analyzer cannot find the usage of a class programmatically, for example if the class -is loaded dynamically via `Class.forName(String)`. Each of the `group`, `name` and `version` fields separated by `:` of -a `dependency` is interpreted as a regular expression. +A dependency can be excluded from the minimization process, thereby forcing its inclusion the shadow JAR. This is useful +when the dependency analyzer cannot find the usage of a class programmatically, for example if the class is loaded +dynamically via `Class.forName(String)`. Each of the `group`, `name` and `version` fields separated by `:` of a +`dependency` is interpreted as a regular expression. === "Kotlin" @@ -69,9 +69,8 @@ Similar to [`ShadowJar.dependencies`][ShadowJar.dependencies], projects can also } ``` -> When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from +> When excluding a `project`, all dependencies of the excluded `project` are automatically excluded from > minimization as well. - [ShadowJar.dependencies]: ../../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/dependencies.html diff --git a/docs/configuration/relocation/README.md b/docs/configuration/relocation/README.md index 0f64e9b6a..f35125b3e 100644 --- a/docs/configuration/relocation/README.md +++ b/docs/configuration/relocation/README.md @@ -1,13 +1,12 @@ # Relocating Packages -Shadow 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. +Shadow 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. > 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. +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. === "Kotlin" @@ -26,9 +25,9 @@ Any non-class files that are stored within a package structure are also relocate } ``` -The code snippet will rewrite the location for any class in the `junit.framework` to be `shadow.junit`. -For example, the class `junit.framework.TestCase` becomes `shadow.junit.TestCase`. -In the resulting JAR, the class file is relocated from `junit/framework/TestCase.class` to +The code snippet will rewrite the location for any class in the `junit.framework` to be `shadow.junit`. For example, the +class `junit.framework.TestCase` becomes `shadow.junit.TestCase`. In the resulting JAR, the class file is relocated from +`junit/framework/TestCase.class` to `shadow/junit/TestCase.class`. > Relocation operates at a package level. @@ -207,10 +206,10 @@ To configure automatic dependency relocation, set `enableAutoRelocation = true` > 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 will automatically add dependencies to your class path. You may need to remove these +> Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove +> these > dependencies if you do not intend to shadow them into your library. - ## Relocating Kotlin Standard Library It is not recommended to relocate Kotlin Standard Library if you are using [Kotlin Metadata][kotlin-metadata] or @@ -246,7 +245,6 @@ This is useful in some cases like [#759](https://github.com/GradleUp/shadow/issu [Configuring Shadowed Dependencies](../dependencies/README.md) for more information about `configurations`. - [#1622]: https://github.com/GradleUp/shadow/issues/1622 [kotlin-metadata]: https://kotlinlang.org/docs/metadata-jvm.html [kotlin-reflection]: https://kotlinlang.org/docs/reflection.html diff --git a/docs/custom-tasks/README.md b/docs/custom-tasks/README.md index 378d67910..59bf742bf 100644 --- a/docs/custom-tasks/README.md +++ b/docs/custom-tasks/README.md @@ -1,9 +1,9 @@ # Creating a Custom ShadowJar Task -The built in [`ShadowJar`][ShadowJar] task only provides an output for the `main` source set of the project. -It is possible to add arbitrary [`ShadowJar`][ShadowJar] tasks to a project. When doing so, ensure that the -[`configurations`][ShadowJar.configurations] property is specified to inform Shadow which dependencies to merge into -the output. +The built in [`ShadowJar`][ShadowJar] task only provides an output for the `main` source set of the project. It is +possible to add arbitrary [`ShadowJar`][ShadowJar] tasks to a project. When doing so, ensure that the +[`configurations`][ShadowJar.configurations] property is specified to inform Shadow which dependencies to merge into the +output. === "Kotlin" @@ -57,8 +57,8 @@ The code snippet above will generate a shadowed JAR containing both the `main` a ## Creating a Dependencies-Only Shadow JAR -It is also possible to create a shadow JAR that contains *only* the dependencies and none of the project's own -source code. This is accomplished by creating a custom [`ShadowJar`][ShadowJar] task and configuring the +It is also possible to create a shadow JAR that contains *only* the dependencies and none of the project's own source +code. This is accomplished by creating a custom [`ShadowJar`][ShadowJar] task and configuring the [`configurations`][ShadowJar.configurations] property, but **not** adding any project sources with `from(...)`. === "Kotlin" diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 6d370c541..a600180c4 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -109,11 +109,9 @@ Alternatively, the plugin can be added to the buildscript classpath and applied: **NOTE:** The correct maven coordinates for each version of Shadow can be found by referencing the Gradle Plugin documentation [here](https://plugins.gradle.org/plugin/com.gradleup.shadow). -Shadow is a reactive plugin. -This means that applying Shadow by itself will perform no configuration on your project. +Shadow is a reactive plugin. This means that applying Shadow by itself will perform no configuration on your project. Instead, Shadow _reacts_ -This means, that for most users, the `java` or `groovy` plugins must be _explicitly_ applied -to have the desired effect. +This means, that for most users, the `java` or `groovy` plugins must be _explicitly_ applied to have the desired effect. ## Default Java/Kotlin/Groovy Tasks @@ -128,23 +126,23 @@ in their build logic), Shadow will automatically configure the following behavio * Configures the [`ShadowJar`][ShadowJar] task to bundle all dependencies from the `runtimeClasspath` configuration. * Configures the _classifier_ attribute of the [`ShadowJar`][ShadowJar] task to be `'all'` . * Configures the [`ShadowJar`][ShadowJar] task to generate a `Manifest` with: - * Inheriting all configuration from the standard [`Jar`][Jar] task. - * Adds a `Class-Path` attribute to the `Manifest` that appends all dependencies from the `shadow` configuration + * Inheriting all configuration from the standard [`Jar`][Jar] task. + * Adds a `Class-Path` attribute to the `Manifest` that appends all dependencies from the `shadow` configuration * Configures the [`ShadowJar`][ShadowJar] task to _exclude_ any JAR index or cryptographic signature files matching the following patterns: - * `META-INF/INDEX.LIST` - * `META-INF/*.SF` - * `META-INF/*.DSA` - * `META-INF/*.RSA` - * `META-INF/versions/**/module-info.class` - * `module-info.class` + * `META-INF/INDEX.LIST` + * `META-INF/*.SF` + * `META-INF/*.DSA` + * `META-INF/*.RSA` + * `META-INF/versions/**/module-info.class` + * `module-info.class` * Creates and registers the `shadow` component in the project (used for integrating with [`maven-publish`][maven-publish]). ## ShadowJar Command Line options -Sometimes, a user wants to declare the value of an exposed task property on the command line instead of the -build script. Passing property values on the command line is particularly helpful if they change more frequently. +Sometimes, a user wants to declare the value of an exposed task property on the command line instead of the build +script. Passing property values on the command line is particularly helpful if they change more frequently. Here are the options that can be passed to the `shadowJar`: ``` @@ -173,7 +171,6 @@ Refer to [listing command line options](https://docs.gradle.org/current/userguide/custom_tasks.html#sec:listing_task_options). - [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html [JavaPlugin]: https://docs.gradle.org/current/userguide/java_plugin.html [maven-publish]: https://docs.gradle.org/current/userguide/publishing_maven.html diff --git a/docs/images/logo+type.orig.svg b/docs/images/logo+type.orig.svg index 53a67c830..8c1577e05 100644 --- a/docs/images/logo+type.orig.svg +++ b/docs/images/logo+type.orig.svg @@ -1 +1,13 @@ - \ No newline at end of file + + + + + + + + + diff --git a/docs/images/logo.orig.svg b/docs/images/logo.orig.svg index b5ed5c6d2..70eb804f1 100644 --- a/docs/images/logo.orig.svg +++ b/docs/images/logo.orig.svg @@ -1 +1,11 @@ - \ No newline at end of file + + + + + + + + diff --git a/docs/kotlin-plugins/README.md b/docs/kotlin-plugins/README.md index 339865136..d6c44d7c3 100644 --- a/docs/kotlin-plugins/README.md +++ b/docs/kotlin-plugins/README.md @@ -1,8 +1,8 @@ # Integrating with Kotlin Plugins Kotlin standard libraries (stdlib) are added by Kotlin plugins by default via `implementation` (`runtimeClasspath`), -they will be bundled into the shadowed JARs automatically. -If you don't need a standard library at all, you can add the following Gradle property to your gradle.properties file: +they will be bundled into the shadowed JARs automatically. If you don't need a standard library at all, you can add the +following Gradle property to your gradle.properties file: ```properties kotlin.stdlib.default.dependency=false @@ -60,8 +60,8 @@ Shadow works well for Kotlin JVM projects like Java projects. Here is an example } ``` -You can mix the Kotlin JVM plugin with `java-gradle-plugin`, `application`, and other Java plugins, -easily organize your build logic for [Publishing Libraries](../publishing/README.md), +You can mix the Kotlin JVM plugin with `java-gradle-plugin`, `application`, and other Java plugins, easily organize your +build logic for [Publishing Libraries](../publishing/README.md), [Running Applications](../application-plugin/README.md), and so on. ## For Kotlin Multiplatform Plugin @@ -144,6 +144,4 @@ automatically configure additional tasks for bundling the shadowed JAR for its ` } ``` - - [org.jetbrains.kotlin.multiplatform]: https://kotlinlang.org/docs/multiplatform-intro.html diff --git a/docs/multi-project/README.md b/docs/multi-project/README.md index 99d44205a..d48a02ed4 100644 --- a/docs/multi-project/README.md +++ b/docs/multi-project/README.md @@ -1,15 +1,13 @@ # Using Shadow in Multi-Project Builds -When using Shadow in a multi-project build, project dependencies will be treated the same as -external dependencies. -That is a project dependency will be merged into the [`ShadowJar`][ShadowJar] output of the project that -is applying the Shadow plugin. +When using Shadow in a multi-project build, project dependencies will be treated the same as external dependencies. That +is a project dependency will be merged into the [`ShadowJar`][ShadowJar] output of the project that is applying the +Shadow plugin. ## Depending on the Shadow Jar from Another Project -In a multi-project build there may be one project that applies Shadow and another that -requires the shadowed JAR as a dependency. -In this case, use Gradle's normal dependency declaration mechanism to depend on the `shadow` +In a multi-project build there may be one project that applies Shadow and another that requires the shadowed JAR as a +dependency. In this case, use Gradle's normal dependency declaration mechanism to depend on the `shadow` configuration of the shadowed project. === "Kotlin" diff --git a/docs/publishing/README.md b/docs/publishing/README.md index 28028c22b..3323e47fd 100644 --- a/docs/publishing/README.md +++ b/docs/publishing/README.md @@ -3,9 +3,8 @@ ## Publishing with Maven-Publish Plugin The Shadow plugin will automatically configure the necessary tasks in the presence of Gradle's -[`maven-publish`][maven-publish] plugin. -The plugin provides the `shadow` component to configure the publication with the necessary -artifact and dependencies in the POM file. +[`maven-publish`][maven-publish] plugin. The plugin provides the `shadow` component to configure the publication with +the necessary artifact and dependencies in the POM file. === "Kotlin" @@ -127,9 +126,9 @@ you can disable this by setting the `addTargetJvmVersionAttribute` property in t } ``` -The BUNDLING attribute (`org.gradle.dependency.bundling`) of the shadowed variant is set to `shadowed` by default, -it is useful for consumers to distinguish between normal and shadowed dependencies. You can override this attribute by -setting the `bundlingAttribute` property in the `shadow` extension: +The BUNDLING attribute (`org.gradle.dependency.bundling`) of the shadowed variant is set to `shadowed` by default, it is +useful for consumers to distinguish between normal and shadowed dependencies. You can override this attribute by setting +the `bundlingAttribute` property in the `shadow` extension: === "Kotlin" @@ -151,23 +150,19 @@ setting the `bundlingAttribute` property in the `shadow` extension: ## Shadow Configuration and Publishing -The Shadow plugin provides a custom configuration (`configurations.shadow`) to specify -runtime dependencies that are **not** merged into the final JAR file. -When configuring publishing with the Shadow plugin, the dependencies in the `shadow` -configuration, are translated to become `RUNTIME` scoped dependencies of the -published artifact. +The Shadow plugin provides a custom configuration (`configurations.shadow`) to specify runtime dependencies that are +**not** merged into the final JAR file. When configuring publishing with the Shadow plugin, the dependencies in the +`shadow` +configuration, are translated to become `RUNTIME` scoped dependencies of the published artifact. -No other dependencies are automatically configured for inclusion in the POM file. -For example, excluded dependencies are **not** automatically added to the POM file or -if the configuration for merging are modified by specifying -`shadowJar.configurations = [configurations.myConfiguration]`, there is no automatic -configuration of the POM file. +No other dependencies are automatically configured for inclusion in the POM file. For example, excluded dependencies are +**not** automatically added to the POM file or if the configuration for merging are modified by specifying +`shadowJar.configurations = [configurations.myConfiguration]`, there is no automatic configuration of the POM file. -This automatic configuration occurs _only_ when using the above methods for -configuring publishing. If this behavior is not desirable, then publishing **must** +This automatic configuration occurs _only_ when using the above methods for configuring publishing. If this behavior is +not desirable, then publishing **must** be manually configured. - === "Kotlin" ```kotlin @@ -254,8 +249,8 @@ be manually configured. ## Publishing the Shadowed JAR instead of the Original JAR -You may want to publish the shadowed JAR instead of the original JAR. This can be done by trimming -the `archiveClassifier` of the shadowed JAR like the following: +You may want to publish the shadowed JAR instead of the original JAR. This can be done by trimming the +`archiveClassifier` of the shadowed JAR like the following: === "Kotlin" @@ -304,8 +299,8 @@ the `archiveClassifier` of the shadowed JAR like the following: ``` Because the default `archiveClassifier` of [`Jar`][Jar] is `""` (empty), setting the `archiveClassifier` of -[`ShadowJar`][ShadowJar] to `""` (empty) will make collisions between the outputs of these two tasks in some cases. -If you don't need the standard JAR, you can disable the `jar` task like: +[`ShadowJar`][ShadowJar] to `""` (empty) will make collisions between the outputs of these two tasks in some cases. If +you don't need the standard JAR, you can disable the `jar` task like: === "Kotlin" @@ -343,10 +338,9 @@ Or set a different `archiveClassifier` for the standard [`Jar`][Jar] like: ## Publishing the Shadowed Gradle Plugins -The Gradle Publish Plugin introduced support for plugins packaged with Shadow in version 1.0.0. -Starting with this version, plugin projects that apply both Shadow and the Gradle Plugin Publish plugin will be -automatically configured to publish the output of the [`ShadowJar`][ShadowJar] tasks as the consumable artifact for the -plugin. See the +The Gradle Publish Plugin introduced support for plugins packaged with Shadow in version 1.0.0. Starting with this +version, plugin projects that apply both Shadow and the Gradle Plugin Publish plugin will be automatically configured to +publish the output of the [`ShadowJar`][ShadowJar] tasks as the consumable artifact for the plugin. See the [Gradle Plugin Publish docs](https://docs.gradle.org/current/userguide/publishing_gradle_plugins.html#shadow_dependencies) for details. The only thing you need to do from the Shadow side is to empty the `archiveClassifier` like: @@ -526,7 +520,6 @@ We modified `archiveClassifier`, `archiveExtension` and `archiveBaseName` in thi be named `my-artifact-2.0-my-classifier.my-ext` instead of `1.0-all.jar`. - [Jar]: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html [MavenPublication.artifact]: https://docs.gradle.org/current/dsl/org.gradle.api.publish.maven.MavenPublication.html#org.gradle.api.publish.maven.MavenPublication:artifact(java.lang.Object) [ShadowJar]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/index.html