Automatically create developmentOnly configuration

Previously, the developmentOnly configuration, typically used for
Devtools, had to be declared manually. The BootJar and BootWar tasks
then had a property, excludeDevtools, that could be used to control
whether or not Devtools would be excluded from the executable archive.

This commit updates the reaction to the Java plugin being applied to
automatically create the developmentOnly configuration. The classpaths
of bootJar and bootWar are then configured not to include the contents
of the developmentOnly configuration. As a result of this, the
excludeDevtools property is no longer needed and has been deprecated.
Its default has also been changed from true to false to make it easy
to opt in to Devtools, when configured as a development-only
dependency, being included in executable jars and wars by adding
developmentOnly to the classpath of the archive task.

Closes gh-16599

Author: wilkinsona

spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc

@@ -533,12 +533,6 @@ To include devtools support, add the module dependency to your build, as shown i
 .Gradle
 [source,groovy,indent=0,subs="attributes"]
 ----
-	configurations {
-		developmentOnly
-		runtimeClasspath {
-			extendsFrom developmentOnly
-		}
-	}
 	dependencies {
 		developmentOnly("org.springframework.boot:spring-boot-devtools")
 	}
@@ -548,11 +542,12 @@ NOTE: Developer tools are automatically disabled when running a fully packaged a
 If your application is launched from `java -jar` or if it is started from a special classloader, then it is considered a "`production application`".
 If that does not apply to you (i.e. if you run your application from a container), consider excluding devtools or set the `-Dspring.devtools.restart.enabled=false` system property.
 
-TIP: Flagging the dependency as optional in Maven or using a custom `developmentOnly` configuration in Gradle (as shown above) is a best practice that prevents devtools from being transitively applied to other modules that use your project.
+TIP: Flagging the dependency as optional in Maven or using the `developmentOnly` configuration in Gradle (as shown above) prevents devtools from being transitively applied to other modules that use your project.
 
 TIP: Repackaged archives do not contain devtools by default.
-If you want to use a <<using-boot-devtools-remote,certain remote devtools feature>>, you need to disable the `excludeDevtools` build property to include it.
-The property is supported with both the Maven and Gradle plugins.
+If you want to use a <<using-boot-devtools-remote,certain remote devtools feature>>, you need to include it.
+When using the Maven plugin, set the `excludeDevtools` property to `false`.
+When using the Gradle plugin, {spring-boot-gradle-plugin-docs}#packaging-executable-configuring-including-development-only-dependencies[configure the task's classpath to include the `developmentOnly` configuration].
 
 
 

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging.adoc

@@ -149,10 +149,11 @@ include::../gradle/packaging/boot-jar-manifest-main-class.gradle.kts[tags=main-c
 
 
 
-[[packaging-executable-configuring-excluding-devtools]]
-==== Excluding Devtools
-By default, Spring Boot's Devtools module, `org.springframework.boot:spring-boot-devtools`, will be excluded from an executable jar or war.
-If you want to include Devtools in your archive set the `excludeDevtools` property to `false`:
+[[packaging-executable-configuring-including-development-only-dependencies]]
+==== Including Development-only Dependencies
+By default all dependencies declared in the `developmentOnly` configuration will be excluded from an executable jar or war.
+
+If you want to include dependencies declared in the `developmentOnly` configuration in your archive, configure the classpath of its task to include the configuration, as shown in the following example for the `bootWar` task:
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
 .Groovy

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/reacting.adoc

@@ -16,8 +16,9 @@ When Gradle's {java-plugin}[`java` plugin] is applied to a project, the Spring B
 4. Creates a {boot-build-image-javadoc}[`BootBuildImage`] task named `bootBuildImage` that will create a OCI image using a https://buildpacks.io[buildpack].
 5. Creates a {boot-run-javadoc}[`BootRun`] task named `bootRun` that can be used to run your application.
 6. Creates a configuration named `bootArchives` that contains the artifact produced by the `bootJar` task.
-7. Configures any `JavaCompile` tasks with no configured encoding to use `UTF-8`.
-8. Configures any `JavaCompile` tasks to use the `-parameters` compiler argument.
+7. Creates a configuration named `developmentOnly` for dependencies that are only required at development time, such as Spring Boot's Devtools, and should not be packaged in executable jars and wars.
+8. Configures any `JavaCompile` tasks with no configured encoding to use `UTF-8`.
+9. Configures any `JavaCompile` tasks to use the `-parameters` compiler argument.
 
 
 

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-war-include-devtools.gradle

@@ -5,11 +5,14 @@ plugins {
 
 bootWar {
 	mainClassName 'com.example.ExampleApplication'
-	classpath file('spring-boot-devtools-1.2.3.RELEASE.jar')
+}
+
+dependencies {
+	developmentOnly files("spring-boot-devtools-1.2.3.RELEASE.jar")
 }
 
 // tag::include-devtools[]
 bootWar {
-	excludeDevtools = false
+	classpath configurations.developmentOnly
 }
 // end::include-devtools[]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-war-include-devtools.gradle.kts

@@ -7,11 +7,14 @@ plugins {
 
 tasks.getByName<BootWar>("bootWar") {
 	mainClassName = "com.example.ExampleApplication"
-	classpath(file("spring-boot-devtools-1.2.3.RELEASE.jar"))
+}
+
+dependencies {
+	"developmentOnly"(files("spring-boot-devtools-1.2.3.RELEASE.jar"))
 }
 
 // tag::include-devtools[]
 tasks.getByName<BootWar>("bootWar") {
-	isExcludeDevtools = false
+	classpath(configurations["developmentOnly"])
 }
 // end::include-devtools[]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/JavaPluginAction.java

@@ -27,6 +27,7 @@
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
 import org.gradle.api.Task;
+import org.gradle.api.artifacts.Configuration;
 import org.gradle.api.file.FileCollection;
 import org.gradle.api.internal.artifacts.dsl.LazyPublishArtifact;
 import org.gradle.api.plugins.ApplicationPlugin;
@@ -67,6 +68,7 @@ public Class<? extends Plugin<? extends Project>> getPluginClass() {
 	public void execute(Project project) {
 		disableJarTask(project);
 		configureBuildTask(project);
+		configureDevelopmentOnlyConfiguration(project);
 		TaskProvider<BootJar> bootJar = configureBootJarTask(project);
 		configureBootBuildImageTask(project, bootJar);
 		configureArtifactPublication(bootJar);
@@ -92,7 +94,8 @@ private TaskProvider<BootJar> configureBootJarTask(Project project) {
 			bootJar.setGroup(BasePlugin.BUILD_GROUP);
 			SourceSet mainSourceSet = javaPluginConvention(project).getSourceSets()
 					.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
-			bootJar.classpath((Callable<FileCollection>) mainSourceSet::getRuntimeClasspath);
+			bootJar.classpath((Callable<FileCollection>) () -> mainSourceSet.getRuntimeClasspath().minus(
+					project.getConfigurations().getByName(SpringBootPlugin.DEVELOPMENT_ONLY_CONFIGURATION_NAME)));
 			bootJar.conventionMapping("mainClassName", new MainClassConvention(project, bootJar::getClasspath));
 		});
 	}
@@ -157,6 +160,15 @@ private void configureAdditionalMetadataLocations(JavaCompile compile) {
 		compile.doFirst(new AdditionalMetadataLocationsConfigurer());
 	}
 
+	private void configureDevelopmentOnlyConfiguration(Project project) {
+		Configuration developmentOnly = project.getConfigurations()
+				.create(SpringBootPlugin.DEVELOPMENT_ONLY_CONFIGURATION_NAME);
+		developmentOnly
+				.setDescription("Configuration for development-only dependencies such as Spring Boot's DevTools.");
+		project.getConfigurations().getByName(JavaPlugin.RUNTIME_CLASSPATH_CONFIGURATION_NAME)
+				.extendsFrom(developmentOnly);
+	}
+
 	/**
 	 * Task {@link Action} to add additional meta-data locations. We need to use an
 	 * inner-class rather than a lambda due to

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java

@@ -70,6 +70,12 @@ public class SpringBootPlugin implements Plugin<Project> {
 	 */
 	public static final String BOOT_BUILD_IMAGE_TASK_NAME = "bootBuildImage";
 
+	/**
+	 * The name of the {@code developmentOnly} configuration.
+	 * @since 2.3.0
+	 */
+	public static final String DEVELOPMENT_ONLY_CONFIGURATION_NAME = "developmentOnly";
+
 	/**
 	 * The coordinates {@code (group:name:version)} of the
 	 * {@code spring-boot-dependencies} bom.

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/WarPluginAction.java

@@ -19,7 +19,8 @@
 import org.gradle.api.Action;
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
-import org.gradle.api.artifacts.Configuration;
+import org.gradle.api.artifacts.ConfigurationContainer;
+import org.gradle.api.file.FileCollection;
 import org.gradle.api.internal.artifacts.dsl.LazyPublishArtifact;
 import org.gradle.api.plugins.BasePlugin;
 import org.gradle.api.plugins.WarPlugin;
@@ -63,12 +64,15 @@ private TaskProvider<BootWar> configureBootWarTask(Project project) {
 			bootWar.setDescription("Assembles an executable war archive containing webapp"
 					+ " content, and the main classes and their dependencies.");
 			bootWar.providedClasspath(providedRuntimeConfiguration(project));
+			bootWar.setClasspath(bootWar.getClasspath().minus(
+					project.getConfigurations().getByName(SpringBootPlugin.DEVELOPMENT_ONLY_CONFIGURATION_NAME)));
 			bootWar.conventionMapping("mainClassName", new MainClassConvention(project, bootWar::getClasspath));
 		});
 	}
 
-	private Configuration providedRuntimeConfiguration(Project project) {
-		return project.getConfigurations().getByName(WarPlugin.PROVIDED_RUNTIME_CONFIGURATION_NAME);
+	private FileCollection providedRuntimeConfiguration(Project project) {
+		ConfigurationContainer configurations = project.getConfigurations();
+		return configurations.getByName(WarPlugin.PROVIDED_RUNTIME_CONFIGURATION_NAME);
 	}
 
 	private void configureArtifactPublication(TaskProvider<BootWar> bootWar) {

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/BootArchive.java

@@ -118,15 +118,21 @@ public interface BootArchive extends Task {
 	 * {@code false}.
 	 * @return {@code true} if the Devtools jar should be excluded, or {@code false} if
 	 * not
+	 * @deprecated since 2.3.0 in favour of configuring a classpath that does not include
+	 * development-only dependencies
 	 */
 	@Input
+	@Deprecated
 	boolean isExcludeDevtools();
 
 	/**
 	 * Sets whether or not the Devtools jar should be excluded.
 	 * @param excludeDevtools {@code true} if the Devtools jar should be excluded, or
 	 * {@code false} if not
+	 * @deprecated since 2.3.0 in favour of configuring a classpath that does not include
+	 * development-only dependencies
 	 */
+	@Deprecated
 	void setExcludeDevtools(boolean excludeDevtools);
 
 }

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/BootArchiveSupport.java

@@ -76,7 +76,7 @@ class BootArchiveSupport {
 
 	private LaunchScriptConfiguration launchScript;
 
-	private boolean excludeDevtools = true;
+	private boolean excludeDevtools = false;
 
 	BootArchiveSupport(String loaderMainClass, Spec<FileCopyDetails> librarySpec,
 			Function<FileCopyDetails, ZipCompression> compressionResolver) {