From 33520bc427cb8a01c24c01fa0fb12ff7d504048a Mon Sep 17 00:00:00 2001 From: John Engelman Date: Mon, 20 Mar 2023 14:48:51 -0500 Subject: [PATCH] add note about plugin-publish --- src/docs/changes/README.md | 5 ++++- src/docs/plugins/README.md | 32 +++++++++++++++++++++----------- 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/src/docs/changes/README.md b/src/docs/changes/README.md index 666cae4ca..25068614d 100644 --- a/src/docs/changes/README.md +++ b/src/docs/changes/README.md @@ -8,10 +8,13 @@ ## v8.1.0 (2023-02-26) -**BREAKING CHANGE**: Due to adoption of the latest version of the `com.gradle.plugin-publish` plugin, the maven GAV coordinates have changed as of this version. +**BREAKING CHANGE:** Due to adoption of the latest version of the `com.gradle.plugin-publish` plugin, the maven GAV coordinates have changed as of this version. The correct coordinates now align with the plugin ID itself: `group=com.github.johnrengelman, artifact=shadow, version=`. For example, `classpath("com.github.johnrengelman:shadow:8.1.0")` is the correct configuration for this version. +**BREAKING CHANGE:** The `ConfigureShadowRelocation` task was removed as of this version to better support Gradle configuration caching. +Instead, use the `enableRelocation = true` and `relocationPrefix = ""` settings on the `ShadowJar` task type. + [Release Notes](https://github.com/johnrengelman/shadow/releases/tag/8.1.0) ## v8.0.0 (2023-02-24) diff --git a/src/docs/plugins/README.md b/src/docs/plugins/README.md index 4f3ca3fcb..0ded9d0c0 100644 --- a/src/docs/plugins/README.md +++ b/src/docs/plugins/README.md @@ -5,18 +5,10 @@ conflicts with the same dependency provided by the Gradle runtime. If this is th to relocate your dependencies to a different package name to avoid the collision. Configuring the relocation has always been possible, but the build author is required to know all the package names -before hand. Shadow v2.0 corrects this by introducing a new task type `ConfigureShadowRelocation`. -Tasks of this type are configured to target an instance of a `ShadowJar` task and run immediately before it. +beforehand. As of Shadow v8.1.0, automatic package relocation can be enabled by setting the `enabledRelocation` +and `relocationPrefix` settings on any `ShadowJar` task. -The `ConfigureShadowRelocation` task, scans the dependencies from the configurations specified on the associated -`ShadowJar` task and collects the package names contained within them. It then configures relocation for these -packages using the specified `prefix` on the associated `ShadowJar` task. - -While this is useful for developing Gradle plugins, nothing about the `ConfigureShadowRelocation` task is tied to -Gradle projects. It can be used for standard Java or Groovy projects. - -A simple Gradle plugin can use this feature by applying the `shadow` plugin and configuring the relocation task -to execute before the `shadowJar` tasks: +A simple Gradle plugin can use this feature by applying the `shadow` plugin and configuring the `shadowJar` task for relocation. ```groovy no-plugins import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar @@ -48,6 +40,12 @@ normal `compile` configuration. These 2 dependencies are provided by Gradle to c provided by the Gradle runtime when executing the plugin. Thus, it is **not** advisable to bundle these dependencies with your plugin. +## Publishing 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` 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. + ## Special Handling of the Java Gradle Plugin Development Plugin The Java Gradle Plugin Development plugin, `java-gradle-plugin`, automatically adds the full Gradle API to the `compile` @@ -57,3 +55,15 @@ included in the resultant shadow jar. Virtually: // needed to prevent inclusion of gradle-api into shadow JAR configurations.compile.dependencies.remove dependencies.gradleApi() + +## Automatic package relocation with Shadow prior to v8.1.0 + +Prior to Shadow v8.1.0, Shadow handled this by introducing a new task type `ConfigureShadowRelocation`. +Tasks of this type are configured to target an instance of a `ShadowJar` task and run immediately before it. + +The `ConfigureShadowRelocation` task, scans the dependencies from the configurations specified on the associated +`ShadowJar` task and collects the package names contained within them. It then configures relocation for these +packages using the specified `prefix` on the associated `ShadowJar` task. + +While this is useful for developing Gradle plugins, nothing about the `ConfigureShadowRelocation` task is tied to +Gradle projects. It can be used for standard Java or Groovy projects. \ No newline at end of file