Backport: Rewrite Build Lifecycle documentation in a consistent docs voice

subprojects/docs/src/docs/userguide/api/kotlin_dsl.adoc

@@ -158,7 +158,7 @@ Groovy DSL script files use the `.gradle` file name extension.
 Kotlin DSL script files use the `.gradle.kts` file name extension.
 ====
 
-To activate the Kotlin DSL, simply use the `.gradle.kts` extension for your build scripts in place of `.gradle`. That also applies to the <<build_lifecycle#sec:settings_file,settings file>> — for example `settings.gradle.kts` — and <<init_scripts#init_scripts,initialization scripts>>.
+To activate the Kotlin DSL, simply use the `.gradle.kts` extension for your build scripts in place of `.gradle`. That also applies to the <<organizing_gradle_projects#sec:settings_file,settings file>> — for example `settings.gradle.kts` — and <<init_scripts#init_scripts,initialization scripts>>.
 
 Note that you can mix Groovy DSL build scripts with Kotlin DSL ones, i.e. a Kotlin DSL build script can apply a Groovy DSL one and each project in a multi-project build can use either one.
 

subprojects/docs/src/docs/userguide/authoring-builds/organizing_gradle_projects.adoc

@@ -89,17 +89,21 @@ While those conventions can be reconfigured, it makes it harder to build script
 Try to stick to the default conventions as much as possible except if you need to adapt to the layout of a legacy project.
 Refer to the reference page of the relevant plugin to learn about its default conventions.
 
+[[sec:settings_file]]
 == Always define a settings file
 
 Gradle tries to locate a `settings.gradle` (Groovy DSL) or a `settings.gradle.kts` (Kotlin DSL) file with every invocation of the build.
 For that purpose, the runtime walks the hierarchy of the directory tree up to the root directory.
 The algorithm stops searching as soon as it finds the settings file.
 
 Always add a `settings.gradle` to the root directory of your build to avoid the initial performance impact.
-This recommendation applies to single project builds as well as multi-project builds.
 The file can either be empty or define the desired name of the project.
 
-A typical Gradle project with a settings file look as such:
+A multi-project build must have a `settings.gradle(.kts)` file in the root project of the multi-project hierarchy.
+It is required because the settings file defines which projects are taking part in a <<multi_project_builds.adoc#multi_project_builds,multi-project build>>.
+Besides defining included projects, you might need it to <<organizing_gradle_projects.adoc#organizing_gradle_projects,add libraries to your build script classpath>>.
+
+The following example shows a standard Gradle project layout:
 
 ====
 [.multi-language-sample]

subprojects/docs/src/docs/userguide/authoring-builds/writing_build_scripts.adoc

@@ -96,7 +96,7 @@ The `Project` object provides some standard properties, which are available in y
 .Script with other targets
 ====
 The _build scripts_ described here target `Project` objects.
-There are also <<build_lifecycle.adoc#sec:settings_file,settings scripts>> and <<init_scripts.adoc#init_scripts,init scripts>> that respectively target link:{groovyDslPath}/org.gradle.api.initialization.Settings.html[Settings] and link:{groovyDslPath}/org.gradle.api.invocation.Gradle.html[Gradle] objects.
+There are also <<organizing_gradle_projects.adoc#sec:settings_file,settings scripts>> and <<init_scripts.adoc#init_scripts,init scripts>> that respectively target link:{groovyDslPath}/org.gradle.api.initialization.Settings.html[Settings] and link:{groovyDslPath}/org.gradle.api.invocation.Gradle.html[Gradle] objects.
 ====
 
 [[sec:the_script_api]]

subprojects/docs/src/docs/userguide/migration/migrating_from_groovy_to_kotlin_dsl.adoc

@@ -143,7 +143,7 @@ Kotlin DSL script files use the `.gradle.kts` file name extension.
 
 To use the Kotlin DSL, simply name your files `build.gradle.kts` instead of `build.gradle`.
 
-The <<build_lifecycle.adoc#sec:settings_file,settings file>>, `settings.gradle`, can also be renamed `settings.gradle.kts`.
+The <<organizing_gradle_projects.adoc#sec:settings_file,settings file>>, `settings.gradle`, can also be renamed `settings.gradle.kts`.
 
 In a multi-project build, you can have some modules using the Groovy DSL (with `build.gradle`) and others using the Kotlin DSL (with `build.gradle.kts`).
 

subprojects/docs/src/docs/userguide/migration/upgrading_version_6.adoc

@@ -297,7 +297,7 @@ The `layout` method taking a configuration block has been removed and is replace
 A Gradle build is defined by its `settings.gradle(.kts)` file found in the current or parent directory.
 Without a settings file, a Gradle build is undefined and Gradle produces an error when attempting to execute tasks.
 
-To fix this error, <<build_lifecycle.adoc#sec:settings_file,create a `settings.gradle(.kts)` file>> for the build.
+To fix this error, <<organizing_gradle_projects.adoc#sec:settings_file,create a `settings.gradle(.kts)` file>> for the build.
 
 Exceptions to this are invoking Gradle with the `init` task or using diagnostic command line flags, such as `--version`.
 

subprojects/docs/src/docs/userguide/reference/directory_layout.adoc

@@ -107,7 +107,7 @@ Overall, the anatomy of a typical project root directory looks roughly as follow
 <4> Contains the JAR file and configuration of the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>
 <5> Project-specific <<build_environment.adoc#sec:gradle_configuration_properties,Gradle configuration properties>>
 <6> Scripts for executing builds using the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>
-<7> The project's <<build_lifecycle.adoc#sec:settings_file, settings file>> where the list of subprojects is defined
+<7> The project's <<organizing_gradle_projects.adoc#sec:settings_file, settings file>> where the list of subprojects is defined
 <8> Usually a project is organized into one or multiple subprojects
 <9> Each subproject has its own Gradle build script
 

subprojects/docs/src/snippets/buildlifecycle/projectEvaluateEvents/groovy/build.gradle

@@ -1,18 +1,17 @@
 // tag::after-evaluate[]
-allprojects {
-    afterEvaluate { project ->
-        if (project.hasTests) {
-            println "Adding test task to $project"
-            project.task('test') {
-                doLast {
-                    println "Running tests for $project"
-                }
+gradle.beforeProject { project ->
+    project.ext.set("hasTests", false)
+}
+
+gradle.afterProject { project ->
+    if (project.ext.has("hasTests") && project.ext.get("hasTests") as Boolean) {
+        def projectString = project.toString()
+        println "Adding test task to $projectString"
+        project.task('test') {
+            doLast {
+                println "Running tests for $projectString"
             }
         }
     }
 }
 // end::after-evaluate[]
-
-allprojects {
-    ext.hasTests = false
-}

subprojects/docs/src/snippets/buildlifecycle/projectEvaluateEvents/kotlin/build.gradle.kts

@@ -1,15 +1,16 @@
 // tag::after-evaluate[]
-allprojects {
+gradle.beforeProject {
     // Set a default value
-    extra["hasTests"] = false
+    project.ext.set("hasTests", false)
+}
 
-    afterEvaluate {
-        if (extra["hasTests"] as Boolean) {
-            println("Adding test task to $project")
-            tasks.register("test") {
-                doLast {
-                    println("Running tests for $project")
-                }
+gradle.afterProject {
+    if (project.ext.has("hasTests") && project.ext.get("hasTests") as Boolean) {
+        val projectString = project.toString()
+        println("Adding test task to $projectString")
+        tasks.register("test") {
+            doLast {
+                println("Running tests for $projectString")
             }
         }
     }