Merge release into master (#28989)

platforms/core-runtime/launcher/src/main/resources/release-features.txt

@@ -0,0 +1,3 @@
+ - Running Gradle on Java 22
+ - Configurable Gradle daemon JVM
+ - Improved IDE performance for large projects

platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/writing_settings_files.adoc

@@ -142,7 +142,7 @@ pluginManagement {                                          // <1>
 }
 
 plugins {                                                   // <2>
-    id("org.gradle.toolchains.fake") version "0.6.0"
+    id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
 }
 
 rootProject.name = "root-project"                           // <3>
@@ -158,9 +158,9 @@ include("sub-project-b")
 include("sub-project-c")
 ----
 <1> Define the location of plugins
-<2> Apply plugins.
+<2> Apply settings plugins.
 <3> Define the root project name.
-<4> Define build-wide repositories.
+<4> Define dependency resolution strategies.
 <5> Add subprojects to the build.
 =====
 
@@ -177,7 +177,7 @@ pluginManagement {                                          // <1>
 }
 
 plugins {                                                   // <2>
-    id 'org.gradle.toolchains.fake' version '0.6.0'
+    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.8.0'
 }
 
 rootProject.name = 'root-project'                           // <3>
@@ -193,18 +193,19 @@ include('sub-project-b')
 include('sub-project-c')
 ----
 <1> Define the location of plugins.
-<2> Apply plugins.
+<2> Apply settings plugins.
 <3> Define the root project name.
-<4> Define build-wide repositories.
+<4> Define dependency resolution strategies.
 <5> Add subprojects to the build.
 =====
 ====
 
 === 1. Define the location of plugins
 
-The settings file can optionally define the plugins your project uses with link:{javadocPath}/org/gradle/plugin/management/PluginManagementSpec.html[`pluginManagement`], including binary repositories such as the Gradle Plugin Portal or other Gradle builds using `includeBuild`:
+The settings file can optionally manage plugin versions and repositories for your build with link:{javadocPath}/org/gradle/plugin/management/PluginManagementSpec.html[`pluginManagement`]
+It provides a centralized way to define which plugins should be used in your project and from which repositories they should be resolved.
 
-[source]
+[source,kotlin]
 ----
 pluginManagement {
     repositories {
@@ -214,41 +215,40 @@ pluginManagement {
 }
 ----
 
-You can also include plugins and plugin dependency resolution strategies in this block.
-
-=== 2. Apply plugins
+=== 2. Apply settings plugins
 
-The settings file can optionally declare the link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[plugins] that may be applied later, which can add shared configuration among several builds / subprojects:
+The settings file can optionally link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[apply plugins] that are required for configuring the settings of the project.
+These are commonly the link:https://plugins.gradle.org/plugin/com.gradle.develocity[Develocity plugin] and the link:https://plugins.gradle.org/plugin/org.gradle.toolchains.foojay-resolver-convention[Toolchain Resolver plugin] in the example below.
 
-Plugins applied to the settings only affect the `Settings` object.
+Plugins applied in the settings file only affect the `Settings` object.
 
-[source]
+[source,kotlin]
 ----
 plugins {
-    id("org.gradle.toolchains.fake") version "0.6.0"
+  id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
 }
 ----
 
-This is typically used to ensure that all subprojects use the same plugin version.
-
 === 3. Define the root project name
 
 The settings file defines your project name using the link:{javadocPath}/org/gradle/api/initialization/ProjectDescriptor.html[`rootProject.name` property]:
 
-[source]
+[source,kotlin]
 ----
 rootProject.name = "root-project"
 ----
 
 There is only one root project per build.
 
-=== 4. Define build-wide repositories
+=== 4. Define dependency resolution strategies
 
-The settings file can optionally link:{javadocPath}/org/gradle/api/initialization/resolve/DependencyResolutionManagement.html[define] the locations of components your project relies on (as well as how to resolve them) using `repositories` such as binary repositories like Maven Central and/or other Gradle builds using `includeBuild`:
+The settings file can optionally link:{javadocPath}/org/gradle/api/initialization/resolve/DependencyResolutionManagement.html[define rules and configurations] for dependency resolution across your project(s).
+It provides a centralized way to manage and customize dependency resolution.
 
-[source]
+[source,kotlin]
 ----
 dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
     repositories {
         mavenCentral()
     }
@@ -261,27 +261,29 @@ You can also include version catalogs in this section.
 
 The settings file defines the structure of the project by adding all the subprojects using the link:{javadocPath}/org/gradle/api/initialization/Settings.html[`include`] statement:
 
-[source]
+[source,kotlin]
 ----
 include("app")
 include("business-logic")
 include("data-model")
 ----
 
+You can also include entire builds using link:{javadocPath}/org/gradle/api/initialization/IncludedBuild.html[`includeBuild`].
+
 == Settings File Scripting
 
 There are many more properties and methods on the `Settings` object that you can use to configure your build.
 
 It's important to remember that while many Gradle scripts are typically written in short Groovy or Kotlin syntax, every item in the settings script is essentially invoking a method on the `Settings` object in the Gradle API:
 
-[source]
+[source,kotlin]
 ----
 include("app")
 ----
 
 Is actually:
 
-[source]
+[source,kotlin]
 ----
 settings.include("app")
 ----
@@ -290,7 +292,7 @@ Additionally, the full power of the Groovy and Kotlin languages is available to
 
 For example, instead of using `include` many times to add subprojects, you can iterate over the list of directories in the project root folder and include them automatically:
 
-[source]
+[source,kotlin]
 ----
 rootDir.listFiles().filter { it.isDirectory && (new File(it, "build.gradle.kts").exists()) }.forEach {
     include(it.name)

platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/custom_plugins.adoc

@@ -24,7 +24,7 @@ By applying plugins, users can easily add new features to their build process wi
 This plugin-based approach allows Gradle to be lightweight and modular.
 It also promotes code reuse and maintainability, as plugins can be shared across projects or within an organization.
 
-Before reading this chapter, it's recommended that you first read the <<gradle_directories.adoc#gradle_directories,Learning The Basics>> and complete the <<partr1_gradle_init.adoc#partr1_gradle_init,Tutorial>>.
+Before reading this chapter, it's recommended that you first read <<gradle_directories.adoc#gradle_directories,Learning The Basics>> and complete the <<partr1_gradle_init.adoc#partr1_gradle_init,Tutorial>>.
 
 == Plugins Introduction
 
@@ -57,7 +57,7 @@ There are three types of *custom plugins*:
 
 |<<sec:build_script_plugins,1>>
 |<<sec:build_script_plugins,Script plugins>>
-|Build script or script file
+|A `.gradle(.kts)` script file
 |A local plugin
 |Plugin is automatically compiled and included in the classpath of the build script.
 
@@ -77,14 +77,14 @@ There are three types of *custom plugins*:
 [[sec:build_script_plugins]]
 == Script plugins
 
-*Script plugins* are typically small, local plugins written in build or scropt files for tasks specific to a single build or project.
+*Script plugins* are typically small, local plugins written in script files for tasks specific to a single build or project.
 They do not need to be reused across multiple projects.
-Build script plugins *are not recommended* but many other forms of plugins evolve from build script plugins.
+Script plugins *are not recommended* but many other forms of plugins evolve from script plugins.
 
-To create a Gradle plugin, you need to write a class that implements the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface in a `gradle(.kts)` file.
+To create a plugin, you need to write a class that implements the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface.
 
 [[sec:writing_a_simple_plugin]]
-The following sample creates a `GreetingPlugin` in a build file, which adds a `hello` task to a project when applied:
+The following sample creates a `GreetingPlugin`, which adds a `hello` task to a project when applied:
 
 ====
 include::sample[dir="snippets/customPlugins/customPlugin/kotlin",files="build.gradle.kts[tag=no-script-plugin]"]
@@ -96,11 +96,12 @@ $ gradle -q hello
 include::{snippetsPath}/customPlugins/customPlugin/tests/customPlugin.out[]
 ----
 
-The `Project` object is passed as a parameter in `apply()`, which the plugin can use to configure the project however it needs to (such as adding tasks, configuring dependencies, etc.)
+The `Project` object is passed as a parameter in `apply()`, which the plugin can use to configure the project however it needs to (such as adding tasks, configuring dependencies, etc.).
+In this example, the plugin is written directly in the build file which is *not a recommended practice*.
 
-When the plugin is written in a separate script, it can be applied using `apply(from = " ")` or `apply from: ''`.
-
-In the example below, the script plugin is create in the `other.gradle(.kts)` file and the plugin is applied in `build.gradle(.kts)`:
+When the plugin is written in a separate script file, it can be applied using `apply(from = "file_name.gradle.kts")` or `apply from: 'file_name.gradle'`.
+In the example below, the plugin is coded in the `other.gradle(.kts)` script file.
+Then, the `other.gradle(.kts)` is applied to `build.gradle(.kts)` using `apply from`:
 
 ====
 include::sample[dir="snippets/customPlugins/customPlugin/kotlin",files="other.gradle.kts[]"]
@@ -117,6 +118,8 @@ $ gradle -q hi
 include::{snippetsPath}/customPlugins/customPlugin/tests/customPluginScript.out[]
 ----
 
+**Script plugins should be avoided.**
+
 [[sec:precompile_script_plugin]]
 == Precompiled script plugins
 

platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins.adoc

@@ -59,7 +59,7 @@ Here is a breakdown of all options for implementing Gradle plugins:
 |Groovy DSL
 |Pre-compiled script plugin
 |a `.gradle` file.
-|Nofootnote:2[It is recommended to use a statically-typed language like *Java* or *Kotlin* for implementing plugins to reduce the likelihood of binary incompatibilities. If using Groovy, consider using *statically compiled Groovy*.]
+|Okfootnote:2[It is recommended to use a statically-typed language like *Java* or *Kotlin* for implementing plugins to reduce the likelihood of binary incompatibilities. If using Groovy, consider using *statically compiled Groovy*.]
 
 |5
 |Java
@@ -68,16 +68,16 @@ Here is a breakdown of all options for implementing Gradle plugins:
 |Yes
 
 |6
-|Kotlin
+|Kotlin / Kotlin DSL
 |Binary plugin
-|an abstract class that implements the `apply(Project project)` method of the `Plugin<Project>` interface in Kotlin.
+|an abstract class that implements the `apply(Project project)` method of the `Plugin<Project>` interface in Kotlin and/or Kotlin DSL.
 |Yes
 
 |7
-|Groovy
+|Groovy / Groovy DSL
 |Binary plugin
-|an abstract class that implements the `apply(Project project)` method of the `Plugin<Project>` interface in Groovy.
-|Nofootnote:2[]
+|an abstract class that implements the `apply(Project project)` method of the `Plugin<Project>` interface in Groovy and/or Groovy DSL.
+|Okfootnote:2[]
 
 |8
 |Scala

platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_binary.adoc

@@ -212,7 +212,7 @@ include::sample[dir="snippets/developingPlugins/pluginExtension/groovy",files="b
 
 As the number of exposed properties grows, you should introduce a nested, more expressive structure.
 
-The following code snippet adds a new configuration block named `customData` as part of the extension.
+The following code snippet adds a new configuration block named `siteInfo` as part of the extension.
 This provides a stronger indication of what those properties mean:
 
 ====
@@ -223,13 +223,13 @@ include::sample[dir="snippets/developingPlugins/pluginExtension/groovy",files="b
 Implementing the backing objects for such an extension is simple.
 First, introduce a new data object for managing the properties `websiteUrl` and `vcsUrl`:
 
-.CustomData.java
+.SiteInfo.java
 [source,java]
 ----
-include::{snippetsPath}/developingPlugins/pluginExtension/groovy/buildSrc/src/main/java/org/myorg/CustomData.java[tags=snippet]
+include::{snippetsPath}/developingPlugins/pluginExtension/groovy/buildSrc/src/main/java/org/myorg/SiteInfo.java[tags=snippet]
 ----
 
-In the extension, create an instance of the `CustomData` class and a method to delegate the captured values to the data instance.
+In the extension, create an instance of the `siteInfo` class and a method to delegate the captured values to the data instance.
 
 To configure underlying data objects, define a parameter of type link:{javadocPath}/org/gradle/api/Action.html[Action].
 

platforms/documentation/docs/src/docs/userguide/authoring-builds/tasks/implementing_custom_tasks.adoc

@@ -24,7 +24,7 @@ image::writing-tasks-3.png[]
 
 Custom actionable tasks can be created by extending the `DefaultTask` class and defining inputs, outputs, and actions.
 
-[[sec:task_groups]]
+[[sec:task_in_out]]
 == Task inputs and outputs
 
 Actionable tasks have inputs and outputs.
@@ -1186,7 +1186,7 @@ Here are all available annotations in detail:
 |Property is a one or more input files or directories that represent a Java compile classpath
 
 |`@OutputFile`
-|Property is an output file for the task
+|Property is an output file for the taskfootnote:1[This notation is used to indicate that a task may create a file. If the task has previously created this file, but its inputs change, the task's "output state" is reflected accordingly.]
 
 |`@OutputFiles`
 |Property is one or more output files for the task
@@ -1198,7 +1198,7 @@ Here are all available annotations in detail:
 |Property is one or more output directories for the task
 
 |`@Destroys`
-|Property is one or more files or directories that the task destroys (deletes/removes)
+|Property is one or more files or directories (coming from other tasks) that the task destroys (deletes/removes)footnote:2[This notation is used to specify locations/files that a task will always delete, and these locations/files typically belong to other tasks. This annotation is useful for tasks that clean up after other tasks such as `clean`.]
 
 |`@LocalState`
 |Property is a local state for a task

platforms/documentation/docs/src/docs/userguide/jvm/toolchains.adoc

@@ -178,7 +178,7 @@ WARNING: The examples above use tasks with `RegularFileProperty` and `DirectoryP
 Doing respectively `launcher.get().executablePath`, `launcher.get().metadata.installationPath` or `compiler.get().executablePath` instead will give you the full path for the given toolchain but note that this may realize (and provision) a toolchain eagerly.
 
 [[sec:auto_detection]]
-== Auto detection of installed toolchains
+== Auto-detection of installed toolchains
 
 By default, Gradle automatically detects local JRE/JDK installations so no further configuration is required by the user.
 The following is a list of common package managers, tools, and locations that are supported by the JVM auto-detection.
@@ -307,7 +307,7 @@ gradle -q javaToolchains
 This can help to debug which toolchains are available to the build, how they are detected and what kind of metadata Gradle knows about those toolchains.
 
 [[sub:disable_auto_provision]]
-=== How to disable auto provisioning
+=== Disabling auto provisioning
 
 In order to disable auto-provisioning, you can use the `org.gradle.java.installations.auto-download` Gradle property:
 
@@ -321,6 +321,16 @@ Then, stop the Gradle daemon so that it can be reinitialized for the next build.
 You can use the `./gradlew --stop` command to stop the daemon process.
 ====
 
+[[sub:removing_auto_provisioned_toolchain]]
+=== Removing an auto-provisioned toolchain
+
+When removing an auto-provisioned toolchain is necessary, remove the relevant toolchain located in the `/jdks` directory within the <<directory_layout.adoc#dir:gradle_user_home,Gradle User Home>>.
+
+[NOTE]
+====
+The <<gradle_daemon.adoc#gradle_daemon,Gradle Daemon>> caches information about your project, including configuration details such as toolchain paths or versions. Changes to a project's toolchain configuration might only occur once the Gradle Daemon is restarted. It is recommended to  <<gradle_daemon.adoc#sec:stopping_an_existing_daemon,stop the Gradle Daemon>> to ensure that Gradle updates the configuration for subsequent builds.
+====
+
 [[sec:custom_loc]]
 == Custom toolchain locations
 

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/groovy/build.gradle

@@ -5,7 +5,7 @@ plugins {
 site {
     outputDir = layout.buildDirectory.file("mysite")
 
-    customData {
+    siteInfo {
         websiteUrl = 'https://gradle.org'
         vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
     }

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/groovy/buildSrc/src/main/java/org/myorg/SiteExtension.java

@@ -11,10 +11,10 @@ abstract public class SiteExtension {
     abstract public RegularFileProperty getOutputDir();
 
     @Nested
-    abstract public CustomData getCustomData();
+    abstract public SiteInfo getSiteInfo();
 
-    public void customData(Action<? super CustomData> action) {
-        action.execute(getCustomData());
+    public void siteInfo(Action<? super SiteInfo> action) {
+        action.execute(getSiteInfo());
     }
 }
 // end::snippet[]

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/groovy/buildSrc/src/main/java/org/myorg/CustomData.java → platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/groovy/buildSrc/src/main/java/org/myorg/SiteInfo.java

@@ -3,7 +3,7 @@
 import org.gradle.api.provider.Property;
 
 // tag::snippet[]
-abstract public class CustomData {
+abstract public class SiteInfo {
 
     abstract public Property<String> getWebsiteUrl();
 

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/kotlin/build.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 site {
     outputDir = layout.buildDirectory.file("mysite")
 
-    customData {
+    siteInfo {
         websiteUrl = "https://gradle.org"
         vcsUrl = "https://github.com/gradle/gradle-site-plugin"
     }

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/kotlin/buildSrc/src/main/java/org/myorg/SiteExtension.java

@@ -11,10 +11,10 @@ abstract public class SiteExtension {
     abstract public RegularFileProperty getOutputDir();
 
     @Nested
-    abstract public CustomData getCustomData();
+    abstract public SiteInfo getSiteInfo();
 
-    public void customData(Action<? super CustomData> action) {
-        action.execute(getCustomData());
+    public void siteInfo(Action<? super SiteInfo> action) {
+        action.execute(getSiteInfo());
     }
 }
 // end::snippet[]

platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/kotlin/buildSrc/src/main/java/org/myorg/CustomData.java → platforms/documentation/docs/src/snippets/developingPlugins/pluginExtension/kotlin/buildSrc/src/main/java/org/myorg/SiteInfo.java

@@ -3,7 +3,7 @@
 import org.gradle.api.provider.Property;
 
 // tag::snippet[]
-abstract public class CustomData {
+abstract public class SiteInfo {
 
     abstract public Property<String> getWebsiteUrl();