Document how to make a shadowed JAR the default output of a project

docs/multi-project/README.md

@@ -28,7 +28,128 @@ configuration of the shadowed project.
     }
     ```
 
+## Making the Shadowed JAR the Default Artifact
 
+When a project needs to expose the shadowed JAR as its default output — so that consumers can depend on it without
+specifying the `shadow` configuration explicitly — you can reconfigure the consumable configurations `apiElements` and
+`runtimeElements` to publish the shadowed JAR instead of the regular JAR.
+
+As a reminder, configurations like `api` and `implementation` are where dependencies are declared (_declarable_), while
+`apiElements` and `runtimeElements` are what Gradle consumes when projects depend on each other.
+
+By tuning these consumable configurations, a simple declaration like `implementation(project(":api"))` will resolve to
+the shadowed JAR by default, preventing accidental consumption of the unshadowed artifact.
+
+**In the shadowed project (`:api`):**
+
+=== "Kotlin"
+
+    ```kotlin
+    plugins {
+      `java-library`
+      id("com.gradleup.shadow")
+    }
+
+    configurations {
+      named("apiElements") {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.shadowJar)
+      }
+      named("runtimeElements") {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.shadowJar)
+      }
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    plugins {
+      id 'java-library'
+      id 'com.gradleup.shadow'
+    }
+
+    configurations {
+      apiElements {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.named('shadowJar'))
+      }
+      runtimeElements {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.named('shadowJar'))
+      }
+    }
+    ```
+
+!!! important
+
+    Clearing `outgoing.variants` ensures Gradle doesn't select the unshadowed `classes` variant by default during compilation.
+
+**Consuming projects can then depend on `:api` without specifying the `shadow` configuration:**
+
+=== "Kotlin"
+
+    ```kotlin
+    dependencies {
+      implementation(project(":api"))
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    dependencies {
+      implementation project(':api')
+    }
+    ```
+
+### Excluding Transitive Dependencies
+
+If you want to exclude transitive dependencies that were bundled into the shadow JAR, you can add `exclude` rules to the
+configurations as well:
+
+=== "Kotlin"
+
+    ```kotlin
+    configurations {
+      named("apiElements") {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.shadowJar)
+        exclude(group = "com.example", module = "bundled-library")
+      }
+      named("runtimeElements") {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.shadowJar)
+        exclude(group = "com.example", module = "bundled-library")
+      }
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    configurations {
+      apiElements {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.named('shadowJar'))
+        exclude group: 'com.example', module: 'bundled-library'
+      }
+      runtimeElements {
+        outgoing.artifacts.clear()
+        outgoing.variants.clear()
+        outgoing.artifact(tasks.named('shadowJar'))
+        exclude group: 'com.example', module: 'bundled-library'
+      }
+    }
+    ```
 
 [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

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

@@ -192,6 +192,138 @@ class JavaPluginsTest : BasePluginTest() {
     }
   }
 
+  @Issue("https://github.com/GradleUp/shadow/issues/1893")
+  @Test
+  fun consumeShadowedProjectViaApiElementsAndRuntimeElements() {
+    settingsScript.appendText(
+      """
+      include 'client', 'server'
+      """
+        .trimIndent()
+    )
+    projectScript.writeText("")
+
+    path("client/src/main/java/client/Client.java")
+      .writeText(
+        """
+        package client;
+        public class Client {}
+        """
+          .trimIndent()
+      )
+    path("client/build.gradle")
+      .writeText(
+        """
+      ${getDefaultProjectBuildScript("java-library")}
+      dependencies {
+        api 'junit:junit:3.8.2'
+      }
+      $shadowJarTask {
+        relocate 'junit.framework', 'client.junit.framework'
+      }
+      configurations {
+        apiElements {
+          outgoing.artifacts.clear()
+          outgoing.variants.clear()
+          outgoing.artifact($shadowJarTask)
+        }
+        runtimeElements {
+          outgoing.artifacts.clear()
+          outgoing.variants.clear()
+          outgoing.artifact($shadowJarTask)
+        }
+      }
+      """
+          .trimIndent() + lineSeparator
+      )
+
+    path("server/src/main/java/server/Server.java")
+      .writeText(
+        """
+        package server;
+        import client.Client;
+        import client.junit.framework.Test;
+        public class Server {}
+        """
+          .trimIndent()
+      )
+    path("server/build.gradle")
+      .writeText(
+        """
+      ${getDefaultProjectBuildScript("java", applyShadowPlugin = false)}
+      dependencies {
+        // No `configuration: "shadow"` needed!
+        implementation project(':client')
+      }
+      """
+          .trimIndent() + lineSeparator
+      )
+
+    // Running server:jar to ensure it compiles against the shadowed client
+    runWithSuccess(":server:jar")
+
+    // The fact that server compiled successfully against `client.junit.framework.Test`
+    // means it consumed the shadowed artifact during compilation.
+    assertThat(jarPath("server/build/libs/server-1.0.jar")).useAll {
+      containsAtLeast("server/Server.class")
+    }
+  }
+
+  @Issue("https://github.com/GradleUp/shadow/issues/1893")
+  @Test
+  fun excludeRulesPreventBundledDepsOnConsumerClasspath() {
+    settingsScript.appendText("include 'foo', 'consumer'$lineSeparator")
+    projectScript.writeText("")
+
+    path("foo/build.gradle")
+      .writeText(
+        """
+      ${getDefaultProjectBuildScript("java-library")}
+      dependencies {
+        implementation 'my:a:1.0'
+      }
+      configurations {
+        named('apiElements') {
+          outgoing.artifacts.clear()
+          outgoing.variants.clear()
+          outgoing.artifact(tasks.named('shadowJar'))
+          exclude(group: 'my', module: 'a')
+        }
+        named('runtimeElements') {
+          outgoing.artifacts.clear()
+          outgoing.variants.clear()
+          outgoing.artifact(tasks.named('shadowJar'))
+          exclude(group: 'my', module: 'a')
+        }
+      }
+      """
+          .trimIndent() + lineSeparator
+      )
+
+    path("consumer/build.gradle")
+      .writeText(
+        """
+      ${getDefaultProjectBuildScript("java", applyShadowPlugin = false)}
+      dependencies {
+        implementation project(':foo')
+      }
+      tasks.register('printClasspathFiles') {
+        def cp = configurations.runtimeClasspath
+        doLast {
+          cp.files.each { logger.lifecycle(it.name) }
+        }
+      }
+      """
+          .trimIndent() + lineSeparator
+      )
+
+    val result = runWithSuccess(":consumer:printClasspathFiles")
+    assertThat(result.output).all {
+      contains("foo-1.0-all.jar")
+      doesNotContain("a-1.0.jar")
+    }
+  }
+
   @Issue("https://github.com/GradleUp/shadow/issues/1606")
   @Test
   fun shadowExposedCustomSourceSetOutput() {