Support shadowed sources JAR

CHANGELOG.md

@@ -12,6 +12,7 @@
   - Support manifest header relocation via configurable `attributesToRelocate` property.
 - Allow disabling default ProGuard rules in R8 minimization with `R8Spec.useDefaultRules`. ([#2252](https://github.com/GradleUp/shadow/pull/2252))
 - Allow passing classpath files to R8 minimization with `R8Spec.classpath`. ([#2255](https://github.com/GradleUp/shadow/pull/2255))
+- Support shadowed sources JAR. ([#2265](https://github.com/GradleUp/shadow/pull/2265))
 
 ### Changed
 

CONTRIBUTING.md

@@ -105,8 +105,9 @@ When adding new features or public APIs:
 
 - Prefer exact and complete matching using `isEqualTo` for string assertions whenever possible instead of partial
   matching (e.g., `contains`).
-- Prefer complete assertions like `containsOnly` for collections whenever possible instead of partial assertions like
-  `containsAtLeast` or `containsNone`.
+- Prefer complete assertions like `containsOnly` (or `containsExactly` when order matters) for collections whenever
+  possible instead of partial assertions like `containsAtLeast` or `containsNone`. Prefer `containsExactly(...)` over
+  `isEqualTo(listOf(...))` when verifying exact collection elements in order.
 - Raw multiline strings in tests should be constructed using `.trimMargin()`.
 - Prefer `=` property assignment over `.set(...)` in Gradle build scripts (both in documentation snippets and functional
   tests) unless `.set(...)` is explicitly required.

api/shadow.api

@@ -58,6 +58,7 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugi
 	public static final field COMPONENT_NAME Ljava/lang/String;
 	public static final field Companion Lcom/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugin$Companion;
 	public static final field SHADOW_RUNTIME_ELEMENTS_CONFIGURATION_NAME Ljava/lang/String;
+	public static final field SHADOW_SOURCES_ELEMENTS_CONFIGURATION_NAME Ljava/lang/String;
 	public fun <init> (Lorg/gradle/api/component/SoftwareComponentFactory;)V
 	public synthetic fun apply (Ljava/lang/Object;)V
 	public fun apply (Lorg/gradle/api/Project;)V
@@ -69,6 +70,7 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugi
 
 public final class com/github/jengelman/gradle/plugins/shadow/ShadowJavaPlugin$Companion {
 	public final synthetic fun getShadowRuntimeElements (Lorg/gradle/api/artifacts/ConfigurationContainer;)Lorg/gradle/api/NamedDomainObjectProvider;
+	public final synthetic fun getShadowSourcesElements (Lorg/gradle/api/artifacts/ConfigurationContainer;)Lorg/gradle/api/NamedDomainObjectProvider;
 }
 
 public abstract class com/github/jengelman/gradle/plugins/shadow/ShadowKmpPlugin : org/gradle/api/Plugin {
@@ -259,6 +261,7 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar
 	public fun getAddMultiReleaseAttribute ()Lorg/gradle/api/provider/Property;
 	public fun getApiJars ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	protected abstract fun getArchiveOperations ()Lorg/gradle/api/file/ArchiveOperations;
+	public fun getArchiveSourcesFile ()Lorg/gradle/api/file/RegularFileProperty;
 	public fun getConfigurations ()Lorg/gradle/api/provider/SetProperty;
 	public fun getDependencyFilter ()Lorg/gradle/api/provider/Property;
 	public fun getDuplicatesStrategy ()Lorg/gradle/api/file/DuplicatesStrategy;
@@ -267,7 +270,9 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar
 	public fun getExcludes ()Ljava/util/Set;
 	protected abstract fun getExecOperations ()Lorg/gradle/process/ExecOperations;
 	public fun getFailOnDuplicateEntries ()Lorg/gradle/api/provider/Property;
+	public fun getGenerateSourcesJar ()Lorg/gradle/api/provider/Property;
 	public fun getIncludedDependencies ()Lorg/gradle/api/file/ConfigurableFileCollection;
+	public fun getIncludedSourcesJars ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public fun getIncludes ()Ljava/util/Set;
 	public fun getJavaLauncher ()Lorg/gradle/api/provider/Property;
 	public fun getMainClass ()Lorg/gradle/api/provider/Property;
@@ -279,6 +284,7 @@ public abstract class com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar
 	public fun getRelocationPrefix ()Lorg/gradle/api/provider/Property;
 	public fun getRelocators ()Lorg/gradle/api/provider/SetProperty;
 	public fun getSourceSetsClassesDirs ()Lorg/gradle/api/file/ConfigurableFileCollection;
+	public fun getSourceSetsSourceDirs ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public fun getToMinimize ()Lorg/gradle/api/file/ConfigurableFileCollection;
 	public fun getTransformers ()Lorg/gradle/api/provider/SetProperty;
 	public fun mergeGroovyExtensionModules ()V

build.gradle.kts

@@ -146,6 +146,7 @@ dependencies {
   testPluginRuntimeOnly(testKit.map { it.output })
   testPluginRuntimeOnly(libs.foojayResolver)
   testPluginRuntimeOnly(libs.pluginPublish)
+  testPluginRuntimeOnly(libs.dokka)
 
   lintChecks(libs.androidx.gradlePluginLints)
 }

docs/configuration/minimizing/README.md

@@ -131,6 +131,18 @@ rules published in dependency JARs, for example under `META-INF/proguard`.
 > Alternatively, if you use [R8 Repackaging][r8-repackaging] (e.g. `-repackageclasses`), R8 applies embedded rules
 > natively without needing rule rewriting.
 
+> [!NOTE]
+> **Shadowed Sources JAR and R8**
+>
+> R8 operates directly on compiled JVM bytecode rather than source code. When minimizing with R8
+(`minimize { r8 { ... } }`),
+> Shadow cannot determine which source files correspond to classes removed by R8. Therefore, the shadowed sources JAR
+will
+> contain all relocated source files without responding to R8 shrinking results.
+>
+> If you need unused source files to be filtered out of the shadowed sources JAR, use the default dependency analyzer
+> minimization (`minimize()`) instead.
+
 === ":material-language-kotlin: build.gradle.kts"
 
     ```kotlin

docs/getting-started/README.md

@@ -137,8 +137,12 @@ in their build logic), Shadow will automatically configure the following behavio
   - `META-INF/*.RSA`
   - `META-INF/versions/**/module-info.class`
   - `module-info.class`
+- Configures the [`ShadowJar`][ShadowJar] task to generate a companion **Shadowed Sources JAR** containing both
+  project sources and shadowed dependency sources with relocated packages when `java.withSourcesJar()` is enabled (or
+  when [`generateSourcesJar`][ShadowJar.generateSourcesJar] is set to `true`).
 - Creates and registers the `shadow` component in the project (used for integrating with
-  [`maven-publish`][maven-publish]).
+  [`maven-publish`][maven-publish]), including the `shadowSourcesElements` variant when `java.withSourcesJar()` is
+  enabled.
 
 ## ShadowJar Command Line options
 
@@ -155,6 +159,8 @@ Here are the options that can be passed to the `shadowJar`:
 --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.
+--generate-sources-jar                Generates a companion shadowed sources JAR containing project and dependency sources.
+--no-generate-sources-jar             Disables option --generate-sources-jar.
 --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.
@@ -175,5 +181,6 @@ Refer to [listing command line options][listing-command-line-options].
 [JavaPlugin]: https://docs.gradle.org/current/userguide/java_plugin.html
 [maven-publish]: https://docs.gradle.org/current/userguide/publishing_maven.html
 [ShadowJar]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/index.html
+[ShadowJar.generateSourcesJar]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.tasks/-shadow-jar/generate-sources-jar.html
 [gradle-plugin-portal]: https://plugins.gradle.org/plugin/com.gradleup.shadow
 [listing-command-line-options]: https://docs.gradle.org/current/userguide/custom_tasks.html#sec:listing_task_options

docs/kotlin-plugins/README.md

@@ -139,6 +139,9 @@ automatically configure additional tasks for bundling the shadowed JAR for its `
     }
     ```
 
+For details on publishing shadowed artifacts and sources JAR in KMP projects, see
+[Publishing with Kotlin Multiplatform (KMP)][publishing-with-kmp].
+
 ## Kotlin Module Metadata Remapping
 
 Kotlin module metadata (`.kotlin_module`) files contain information about package parts and facades. When relocating
@@ -169,4 +172,5 @@ To explicitly apply this remapping (recommended for future compatibility), add
 [KotlinModuleMetadataTransformer]: ../api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-kotlin-module-metadata-transformer/index.html
 [dependency-on-the-standard-library]: https://kotlinlang.org/docs/gradle-configure-project.html#dependency-on-the-standard-library
 [publishing-libraries]: ../publishing/README.md
+[publishing-with-kmp]: ../publishing/README.md#publishing-with-kotlin-multiplatform-kmp
 [running-applications]: ../application-plugin/README.md