Support disabling Kotlin module metadata remapping

api/shadow.api

@@ -203,7 +203,7 @@ public abstract interface class com/github/jengelman/gradle/plugins/shadow/tasks
 
 public class com/github/jengelman/gradle/plugins/shadow/tasks/ShadowCopyAction : org/gradle/api/internal/file/copy/CopyAction {
 	public static final field Companion Lcom/github/jengelman/gradle/plugins/shadow/tasks/ShadowCopyAction$Companion;
-	public fun <init> (Ljava/io/File;Lkotlin/jvm/functions/Function1;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZLjava/lang/String;)V
+	public fun <init> (Ljava/io/File;Lkotlin/jvm/functions/Function1;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZLjava/lang/String;)V
 	public fun execute (Lorg/gradle/api/internal/file/copy/CopyActionProcessingStream;)Lorg/gradle/api/tasks/WorkResult;
 }
 
@@ -228,6 +228,7 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar
 	public fun getDependencyFilter ()Lorg/gradle/api/provider/Property;
 	public fun getDuplicatesStrategy ()Lorg/gradle/api/file/DuplicatesStrategy;
 	public fun getEnableAutoRelocation ()Lorg/gradle/api/provider/Property;
+	public fun getEnableKotlinModuleRemapping ()Lorg/gradle/api/provider/Property;
 	public fun getExcludes ()Ljava/util/Set;
 	public fun getFailOnDuplicateEntries ()Lorg/gradle/api/provider/Property;
 	public fun getIncludedDependencies ()Lorg/gradle/api/file/ConfigurableFileCollection;

docs/changes/README.md

@@ -14,6 +14,13 @@
 - Add new merge strategy `Fail` to `PropertiesFileTransformer`. ([#1856](https://github.com/GradleUp/shadow/pull/1856))
 - Add `FindResourceInClasspath` task to help with debugging issues with merged duplicate resources. ([#1860](https://github.com/GradleUp/shadow/pull/1860))
 - Add `MergeLicenseResourceTransformer`. ([#1858](https://github.com/GradleUp/shadow/pull/1858))
+- Support disabling relocation of Kotlin module metadata. ([#1875](https://github.com/GradleUp/shadow/pull/1875))
+  ```kotlin
+  tasks.shadowJar {
+    // Disable remapping of Kotlin module metadata (`.kotlin_module`) files. This is enabled by default.
+    enableKotlinModuleRemapping = false
+  }
+  ```
 
 ### Changed
 

docs/getting-started/README.md

@@ -148,17 +148,19 @@ build script. Passing property values on the command line is particularly helpfu
 Here are the options that can be passed to the `shadowJar`:
 
 ```
---add-multi-release-attribute       Adds the multi-release attribute to the manifest if any dependencies contain it.
---no-add-multi-release-attribute    Disables option --add-multi-release-attribute.
---enable-auto-relocation            Enables auto relocation of packages in the dependencies.
---no-enable-auto-relocation         Disables option --enable-auto-relocation.
---fail-on-duplicate-entries         Fails build if the ZIP entries in the shadowed JAR are duplicate.
---no-fail-on-duplicate-entries      Disables option --fail-on-duplicate-entries.
---main-class                        Main class attribute to add to manifest.
---minimize-jar                      Minimizes the jar by removing unused classes.
---no-minimize-jar                   Disables option --minimize-jar.
---relocation-prefix                 Prefix used for auto relocation of packages in the dependencies.
---rerun                             Causes the task to be re-run even if up-to-date.
+--add-multi-release-attribute         Adds the multi-release attribute to the manifest if any dependencies contain it.
+--no-add-multi-release-attribute      Disables option --add-multi-release-attribute.
+--enable-auto-relocation              Enables auto relocation of packages in the dependencies.
+--no-enable-auto-relocation           Disables option --enable-auto-relocation.
+--enable-kotlin-module-remapping      Enables remapping of Kotlin module metadata files.
+--no-enable-kotlin-module-remapping   Disables option --enable-kotlin-module-remapping.
+--fail-on-duplicate-entries           Fails build if the ZIP entries in the shadowed JAR are duplicate.
+--no-fail-on-duplicate-entries        Disables option --fail-on-duplicate-entries.
+--main-class                          Main class attribute to add to manifest.
+--minimize-jar                        Minimizes the jar by removing unused classes.
+--no-minimize-jar                     Disables option --minimize-jar.
+--relocation-prefix                   Prefix used for auto relocation of packages in the dependencies.
+--rerun                               Causes the task to be re-run even if up-to-date.
 ```
 
 Also, you can view more information about the [`ShadowJar`][ShadowJar] task by running the following command:

src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/JavaPluginsTest.kt

@@ -100,6 +100,8 @@ class JavaPluginsTest : BasePluginTest() {
       "--no-add-multi-release-attribute     Disables option --add-multi-release-attribute.",
       "--enable-auto-relocation     Enables auto relocation of packages in the dependencies.",
       "--no-enable-auto-relocation     Disables option --enable-auto-relocation.",
+      "--enable-kotlin-module-remapping     Enables remapping of Kotlin module metadata files.",
+      "--no-enable-kotlin-module-remapping     Disables option --enable-kotlin-module-remapping.",
       "--fail-on-duplicate-entries     Fails build if the ZIP entries in the shadowed JAR are duplicate.",
       "--no-fail-on-duplicate-entries     Disables option --fail-on-duplicate-entries",
       "--main-class     Main class attribute to add to manifest.",

src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/RelocationTest.kt

@@ -603,12 +603,14 @@ class RelocationTest : BasePluginTest() {
   @Issue(
     "https://github.com/GradleUp/shadow/issues/843",
   )
-  @Test
   @OptIn(UnstableMetadataApi::class)
-  fun relocateKotlinModuleFiles() {
+  @ParameterizedTest
+  @ValueSource(booleans = [false, true])
+  fun relocateKotlinModuleFiles(enableKotlinModuleRemapping: Boolean) {
     val originalModuleFilePath = "META-INF/kotlin-stdlib.kotlin_module"
+    val originalModuleFileBytes = requireResourceAsPath(originalModuleFilePath).readBytes()
     val stdlibJar = buildJar("stdlib.jar") {
-      insert(originalModuleFilePath, requireResourceAsPath(originalModuleFilePath).readBytes())
+      insert(originalModuleFilePath, originalModuleFileBytes)
     }
     projectScript.appendText(
       """
@@ -617,18 +619,31 @@ class RelocationTest : BasePluginTest() {
         }
         $shadowJarTask {
           relocate('kotlin', 'my.kotlin')
+          enableKotlinModuleRemapping = $enableKotlinModuleRemapping
         }
       """.trimIndent(),
     )
 
     runWithSuccess(shadowJarPath)
 
     val relocatedModuleFilePath = "META-INF/kotlin-stdlib.shadow.kotlin_module"
-    assertThat(outputShadowedJar).useAll {
-      containsOnly(
-        relocatedModuleFilePath,
-        *manifestEntries,
-      )
+
+    if (enableKotlinModuleRemapping) {
+      assertThat(outputShadowedJar).useAll {
+        containsOnly(
+          relocatedModuleFilePath,
+          *manifestEntries,
+        )
+      }
+    } else {
+      assertThat(outputShadowedJar).useAll {
+        containsOnly(
+          originalModuleFilePath,
+          *manifestEntries,
+        )
+      }
+      assertThat(outputShadowedJar.use { it.getBytes(originalModuleFilePath) }).isEqualTo(originalModuleFileBytes)
+      return
     }
 
     val originalModule = KotlinModuleMetadata.read(requireResourceAsStream(originalModuleFilePath).readBytes())

src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowCopyAction.kt

@@ -43,6 +43,7 @@ public open class ShadowCopyAction(
   private val transformers: Set<ResourceTransformer>,
   private val relocators: Set<Relocator>,
   private val unusedClasses: Set<String>,
+  private val enableKotlinModuleRemapping: Boolean,
   private val preserveFileTimestamps: Boolean,
   private val failOnDuplicateEntries: Boolean,
   private val encoding: String?,
@@ -173,7 +174,7 @@ public open class ShadowCopyAction(
             fileDetails.remapClass()
           }
         }
-        path.endsWith(".kotlin_module") -> {
+        enableKotlinModuleRemapping && path.endsWith(".kotlin_module") -> {
           if (relocators.isEmpty()) {
             fileDetails.writeToZip(path)
           } else {

src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar.kt

@@ -1,7 +1,6 @@
 package com.github.jengelman.gradle.plugins.shadow.tasks
 
 import com.github.jengelman.gradle.plugins.shadow.ShadowBasePlugin
-import com.github.jengelman.gradle.plugins.shadow.ShadowBasePlugin.Companion.shadow
 import com.github.jengelman.gradle.plugins.shadow.internal.DefaultDependencyFilter
 import com.github.jengelman.gradle.plugins.shadow.internal.DefaultInheritManifest
 import com.github.jengelman.gradle.plugins.shadow.internal.MinimizeDependencyFilter
@@ -160,6 +159,19 @@ public abstract class ShadowJar : Jar() {
   @get:Option(option = "enable-auto-relocation", description = "Enables auto relocation of packages in the dependencies.")
   public open val enableAutoRelocation: Property<Boolean> = objectFactory.property(false)
 
+  /**
+   * Enables remapping of Kotlin module metadata (`.kotlin_module`) files.
+   *
+   * If you enable this option, the Kotlin module metadata file paths and their contents will be relocated if they are
+   * matched by any of the configured [relocators]. Someone may want to disable this feature and write their own
+   * [ResourceTransformer]s to handle Kotlin module metadata files in a custom way.
+   *
+   * Defaults to `true`.
+   */
+  @get:Input
+  @get:Option(option = "enable-kotlin-module-remapping", description = "Enables remapping of Kotlin module metadata files.")
+  public open val enableKotlinModuleRemapping: Property<Boolean> = objectFactory.property(true)
+
   /**
    * Prefix used for auto relocation of packages in the dependencies.
    *
@@ -431,6 +443,7 @@ public abstract class ShadowJar : Jar() {
       transformers = transformers.get(),
       relocators = relocators.get() + packageRelocators,
       unusedClasses = unusedClasses,
+      enableKotlinModuleRemapping = enableKotlinModuleRemapping.get(),
       preserveFileTimestamps = isPreserveFileTimestamps,
       failOnDuplicateEntries = failOnDuplicateEntries.get(),
       metadataCharset,

src/test/kotlin/com/github/jengelman/gradle/plugins/shadow/ShadowPropertiesTest.kt

@@ -147,6 +147,7 @@ class ShadowPropertiesTest {
     with(shadowJarTask) {
       assertThat(addMultiReleaseAttribute.get()).isTrue()
       assertThat(enableAutoRelocation.get()).isFalse()
+      assertThat(enableKotlinModuleRemapping.get()).isTrue()
       assertThat(failOnDuplicateEntries.get()).isFalse()
       assertThat(minimizeJar.get()).isFalse()
       assertThat(mainClass.orNull).isNull()