Merge remote-tracking branch 'origin/main' into g/20250311/kotlin-new-app-block

// Conflicts:
//	src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/KmpPluginTest.kt

Author: Goooler

.github/workflows/deploy.yml

@@ -14,4 +14,9 @@ jobs:
         with:
           # Fetch all tags and branches, so that MkDocs could push incremental updates.
           fetch-depth: 0
+      - uses: gradle/actions/setup-gradle@v4
+        with:
+          cache-read-only: true
+      # Prepare API documentations for MkDocs.
+      - run: ./gradlew dokkaHtml --no-configuration-cache
       - uses: ./.github/actions/deploy-site

docs/README.md

@@ -1,16 +1,59 @@
 <div style="text-align: center;">
-  <img src="images/logo.svg" alt="Shadow Gradle Plugin" style="max-width: 300px; height: auto;">
+  <img src="images/logo.svg" alt="Shadow Gradle Plugin" width="300"/>
   <h1><strong>Shadow Gradle Plugin</strong></h1>
-  <p><em>The library author's dependency toolkit</em></p>
 </div>
 
----
+# Introduction
 
-Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
-`com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
-before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
-development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+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`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarInputStream.html) and [`JarOutputStream`](https://docs.oracle.com/javase/8/docs/api/java/util/jar/JarOutputStream.html) to efficiently process dependent libraries
+into the output jar without incurring the I/O overhead of expanding the jars to disk.
 
-If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
-`com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
-and update to the latest version to receive all the latest bug fixes and improvements.
+!!! warning "Plugin ID Change"
+
+    Previously this plugin was developed by [@johnrengelman](https://github.com/johnrengelman) and published under the ID [
+    `com.github.johnrengelman.shadow`](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
+    before maintenance was transferred to the [GradleUp organization](https://github.com/GradleUp) to ensure future
+    development, see [#908](https://github.com/GradleUp/shadow/issues/908).
+    
+    If you are still using the old plugin ID in your build script, we recommend to switch to the new plugin ID [
+    `com.gradleup.shadow`](https://plugins.gradle.org/plugin/com.gradleup.shadow)
+    and update to the latest version to receive all the latest bug fixes and improvements.
+
+## Benefits of Shadow
+
+Shadowing a project output has 2 major use cases:
+
+1. Creating an _executable_ JAR distribution
+2. Bundling and relocating common dependencies in libraries to avoid classpath conflicts
+
+### 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.
+
+Executable JARs contain a JAR MANIFEST that specifies the application Main Class.
+This allows the application to be started with a single command:
+
+```shell
+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.
+
+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.

docs/about/README.md

@@ -1,13 +1,13 @@
 # About This Project
 
-I started this project in December 2012. We were working on converting from a monolithic application into the
+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.
 
-So, Charlie Knudsen and I (John Engelman) set out to port the existing Shade code into a Gradle plugin.
+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.
 
@@ -19,6 +19,7 @@ so Shadow was published there.
 ## Maintainers
 
 * [John Engelman](https://github.com/johnrengelman)
+* [Goooler](https://github.com/Goooler)
 
 ## Contributors
 

docs/changes/README.md

@@ -7,6 +7,7 @@
 
 - Add Kotlin DSL examples in docs. ([#1306](https://github.com/GradleUp/shadow/pull/1306))
 - Support using type-safe dependency accessors in `ShadowJar.dependencies`. ([#1322](https://github.com/GradleUp/shadow/pull/1322))
+- Set `Main-Class` attr for KMP 2.1.0 or above. ([#1337](https://github.com/GradleUp/shadow/pull/1337))
 
 **Changed**
 

docs/configuration/merging/README.md

@@ -1,11 +1,11 @@
 # Controlling JAR Content Merging
 
 Shadow allows for customizing the process by which the output JAR is generated through the
-[`Transformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-transformer/index.html) interface.
+[`ResourceTransformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-resource-transformer/index.html) interface.
 This is a concept that has been carried over from the original Maven Shade implementation.
-A [`Transformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-transformer/index.html) is invoked for each 
+A [`ResourceTransformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-resource-transformer/index.html) is invoked for each 
 entry in the JAR before being written to the final output JAR.
-This allows a [`Transformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-transformer/index.html) to 
+This allows a [`ResourceTransformer`](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-resource-transformer/index.html) to 
 determine if it should process a particular entry and apply any modifications before writing the stream to the output.
 
 === "Kotlin"
@@ -48,7 +48,7 @@ determine if it should process a particular entry and apply any modifications be
     }
     ```
 
-Additionally, a `Transformer` can accept a `Closure` to configure the provided `Transformer`.
+Additionally, a `ResourceTransformer` can accept a `Closure` to configure the provided `ResourceTransformer`.
 
 === "Kotlin"
 
@@ -95,7 +95,7 @@ Additionally, a `Transformer` can accept a `Closure` to configure the provided `
     }
     ```
 
-An instantiated instance of a `Transformer` can also be provided.
+An instantiated instance of a `ResourceTransformer` can also be provided.
 
 === "Kotlin"
 
@@ -254,7 +254,7 @@ method to add this transformer.
 
 ## Merging Log4j2 Plugin Cache Files (`Log4j2Plugins.dat`)
 
-`Log4j2PluginsCacheFileTransformer` is a `Transformer` that merges `META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat` plugin caches from all the jars
+`Log4j2PluginsCacheFileTransformer` is a `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 [Log4j Plugin Descriptor Transformer](https://logging.apache.org/log4j/transform/log4j-transform-maven-shade-plugin-extensions.html#log4j-plugin-cache-transformer).
 
 === "Kotlin"
@@ -355,3 +355,45 @@ It must be added using the [`transform`](https://gradleup.com/shadow/api/shadow/
       }
     }
     ```
+
+## Handling Duplicates Strategy
+
+`ShadowJar` is a subclass of 
+[`org.gradle.api.tasks.AbstractCopyTask`](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.AbstractCopyTask.html), 
+which means it honors the `duplicatesStrategy` property as its parent classes do. There are several strategies to handle:
+
+- `EXCLUDE`: Do not allow duplicates by ignoring subsequent items to be created at the same path.
+- `FAIL`: Throw a `DuplicateFileCopyingException` when subsequent items are to be created at the same path.
+- `INCLUDE`: Do not attempt to prevent duplicates.
+- `INHERIT`: Uses the same strategy as the parent copy specification.
+- `WARN`: Do not attempt to prevent duplicates, but log a warning message when multiple items are to be created at the same path.
+
+You can see more details about them in 
+[`DuplicatesStrategy`](https://docs.gradle.org/current/javadoc/org/gradle/api/file/DuplicatesStrategy.html).
+
+`ShadowJar` recognizes `DuplicatesStrategy.INCLUDE` as the default, if you want to change the strategy, you can 
+override it like:
+
+=== "Kotlin"
+
+    ```kotlin
+    tasks.shadowJar {
+      duplicatesStrategy = DuplicatesStrategy.EXCLUDE // Or something else.
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) {
+      duplicatesStrategy = DuplicatesStrategy.EXCLUDE // Or something else.
+    }
+    ```
+
+Different strategies will lead to different results for `foo/bar` files in the JARs to be merged:
+
+- `EXCLUDE`: The **first** `foo/bar` file will be included in the final JAR.
+- `FAIL`: **Fail** the build with a `DuplicateFileCopyingException` if there are duplicated `foo/bar` files.
+- `INCLUDE`: The **last** `foo/bar` file will be included in the final JAR (the default behavior).
+- `INHERIT`: **Fail** the build with an exception like `Entry .* is a duplicate but no duplicate handling strategy has been set`.
+- `WARN`: The **last** `foo/bar` file will be included in the final JAR, and a warning message will be logged.

docs/configuration/relocation/README.md

@@ -127,3 +127,31 @@ In versions before 8.1.0 it was necessary to configure a separate `ConfigureShad
 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 
 dependencies if you do not intend to shadow them into your library.
+
+## Relocating Project Resources Only
+
+If you want to relocate the resources of the project only and exclude all dependencies (related to a normal JAR but with 
+relocating), you can try out the trick like:
+
+=== "Kotlin"
+
+    ```kotlin
+    tasks.shadowJar {
+      // Empty configurations list will exclude all dependencies.
+      configurations = emptyList()
+      relocate("com.example", "shadow.com.example")
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) {
+      // Empty configurations list will exclude all dependencies.
+      configurations = []
+      relocate 'com.example', 'shadow.com.example'
+    }
+    ```
+
+This is useful in some cases like [#759](https://github.com/GradleUp/shadow/issues/759) mentioned. See 
+[Configuring Shadowed Dependencies](../dependencies/README.md) for more information about `configurations`.

docs/getting-started/README.md

@@ -116,13 +116,16 @@ Instead, Shadow _reacts_
 This means, that for most users, the `java` or `groovy` plugins must be _explicitly_ applied
 to have the desired effect.
 
-## Default Java/Groovy Tasks
+## Default Java/Kotlin/Groovy Tasks
 
-In the presence of the `java` or `groovy` plugins, Shadow will automatically configure the
-following behavior:
+In the presence of the `java`, `org.jetbrains.kotlin.jvm` or `groovy` plugins
+(that apply [JavaPlugin](https://docs.gradle.org/current/userguide/java_plugin.html) in their build logic),
+Shadow will automatically configure the following behavior:
 
 * Adds a `shadowJar` task to the project.
 * Adds a `shadow` configuration to the project.
+* Adds a `shadow` variant to the project.
+* Adds a `shadow` component to the project.
 * Configures the `shadowJar` task to include all sources from the project's `main` sourceSet.
 * Configures the `shadowJar` task to bundle all dependencies from the `runtimeClasspath` configuration.
 * Configures the _classifier_ attribute of the `shadowJar` task to be `'all'` .
@@ -137,10 +140,3 @@ following behavior:
     * `META-INF/versions/**/module-info.class`
     * `module-info.class`
 * Creates and registers the `shadow` component in the project (used for integrating with `maven-publish`).
-
-## Shadowing Gradle Plugins
-
-Shadow ships with a companion task that can be used to automatically discover dependency packages and configure 
-them for relocation. This is useful in projects if you want to relocate all dependencies.
-
-For more details see the section [Using Shadow to Package Gradle Plugins](../plugins/README.md)

docs/plugins/README.md renamed to docs/gradle-plugins/README.md

@@ -0,0 +1,91 @@
+# Integrating with Groovy and Scala Plugins
+
+Shadow also works well for Groovy and Scala, here are integration examples:
+
+For Groovy:
+
+=== "Kotlin"
+
+    ```kotlin
+    plugins {
+      groovy
+      id("com.gradleup.shadow")
+    }
+
+    dependencies {
+      // If you don't want the Groovy standard library to be shadowed, please replace `implementation` with `api`.
+      implementation(localGroovy())
+    }
+
+    tasks.shadowJar {
+      manifest {
+        // Optionally, set the main class for the shadowed JAR.
+        attributes["Main-Class"] = "com.example.Main"
+      }
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    plugins {
+      id 'groovy'
+      id 'com.gradleup.shadow'
+    }
+
+    dependencies {
+      // If you don't want the Groovy standard library to be shadowed, please replace `implementation` with `api`.
+      implementation localGroovy()
+    }
+
+    tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) {
+      manifest {
+        // Optionally, set the main class for the shadowed JAR.
+        attributes 'Main-Class': 'com.example.Main'
+      }
+    }
+    ```
+
+For Scala:
+
+=== "Kotlin"
+
+    ```kotlin
+    plugins {
+      scala
+      id("com.gradleup.shadow")
+    }
+
+    dependencies {
+      // If you don't want the Scala standard library to be shadowed, please replace `implementation` with `api`.
+      implementation("org.scala-lang:scala-library:2.13.16")
+    }
+
+    tasks.shadowJar {
+      manifest {
+        // Optionally, set the main class for the shadowed JAR.
+        attributes["Main-Class"] = "com.example.Main"
+      }
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    plugins {
+      id 'scala'
+      id 'com.gradleup.shadow'
+    }
+
+    dependencies {
+      // If you don't want the Scala standard library to be shadowed, please replace `implementation` with `api`.
+      implementation 'org.scala-lang:scala-library:2.13.16'
+    }
+
+    tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) {
+      manifest {
+        // Optionally, set the main class for the shadowed JAR.
+        attributes 'Main-Class': 'com.example.Main'
+      }
+    }
+    ```