Merge pull request gradle#26992 Authoring Gradle Builds section in Gr…

…adle User Manual

### Details
This is a Documentation change ONLY.

### Context
Major update of **Authoring Gradle Builds**.

### Reviewers: [Link to Build](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74565289:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231116041810%2B0000/docs/userguide/userguide.html)

Please review the finished sections of Authoring Gradle Builds highlighted below:

- [X] [Getting Started](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74565289:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231116041810%2B0000/docs/userguide/getting_started_dev.html)
- [X] [Learning The Basics](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74565289:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231116041810%2B0000/docs/userguide/gradle_directories.html)
- [X] [Tutorial](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74565289:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231116041810%2B0000/docs/userguide/partr1_gradle_init.html)

### Notes:
The **Authoring Gradle Builds** section is for **Build Engineers**. You should assume that they already have the knowledge from the **Running Gradle Builds** sections. Information in those sections should NOT be repeated in these new sections. This section is about how Gradle works and how to customize Gradle (think changing the pedals on the bike).

Co-authored-by: Laura Kassovic <[email protected]>

subprojects/distributions-integ-tests/src/integTest/groovy/org/gradle/SrcDistributionIntegrationSpec.groovy

@@ -38,7 +38,7 @@ class SrcDistributionIntegrationSpec extends DistributionIntegrationSpec {
 
     @Override
     int getMaxDistributionSizeBytes() {
-        return 56 * 1024 * 1024
+        return 58 * 1024 * 1024
     }
 
     @Override

subprojects/docs/src/docs/css/manual.css

@@ -501,7 +501,7 @@ table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-si
 .admonitionblock td.content {
     word-wrap: anywhere;
     background: var(--admonition-background);
-    padding: 1rem 1rem 0rem;
+    padding: 1rem 1rem 1rem;
     width: 100%;
     border-radius: 4px;
 }

subprojects/docs/src/docs/userguide/authoring-builds/basics/build_lifecycle.adoc

@@ -0,0 +1,109 @@
+// Copyright (C) 2023 Gradle, Inc.
+//
+// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://creativecommons.org/licenses/by-nc-sa/4.0/
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+[[build_lifecycle]]
+= Build Lifecycle
+
+As a build author, you define tasks and dependencies between tasks.
+Gradle guarantees that these tasks will execute in order of their dependencies.
+
+image::author-gradle-1.png[]
+
+Your build scripts and plugins configure this dependency graph.
+
+For example, if your project tasks include `build`, `assemble`, `createDocs`, your build script(s) can ensure that they are executed in the order `build` -> `assemble` -> `createDoc`.
+
+== Task Graphs
+
+Gradle builds the task graph *before* executing any task.
+
+Across all projects in the build, tasks form a http://en.wikipedia.org/wiki/Directed_acyclic_graph[Directed Acyclic Graph^] (DAG).
+
+This diagram shows two example task graphs, one abstract and the other concrete, with dependencies between tasks represented as arrows:
+
+image::task-dag-examples.png[]
+
+[[build_lifecycle_events]]
+Both plugins and build scripts contribute to the task graph via the <<tutorial_using_tasks.adoc#sec:task_dependencies,task dependency mechanism>> and <<incremental_build.adoc#sec:task_inputs_outputs,annotated inputs/outputs>>.
+
+[[sec:build_phases]]
+== Build Phases
+
+A Gradle build has three distinct phases.
+
+Gradle runs these phases in order:
+
+Phase 1. Initialization::
+- Detects the `settings.gradle(.kts)` file.
+- Creates a link:{groovyDslPath}/org.gradle.api.initialization.Settings.html[`Settings`] instance.
+- Evaluates the settings file to determine which projects (and included builds) make up the build.
+- Creates a link:{groovyDslPath}/org.gradle.api.Project.html[`Project`] instance for every project.
+Phase 2. Configuration::
+- Evaluates the build scripts, `build.gradle(.kts)`, of every project participating in the build.
+- Creates a task graph for requested tasks.
+Phase 3. Execution::
+- Schedules and executes the selected tasks.
+- Dependencies between tasks determine execution order.
+- Execution of tasks can occur in parallel.
+
+image::build-lifecycle-example.png[]
+
+=== Example
+
+The following example shows which parts of settings and build files correspond to various build phases:
+
+====
+include::sample[dir="snippets/buildlifecycle/basic/kotlin",files="settings.gradle.kts[];build.gradle.kts[]"]
+include::sample[dir="snippets/buildlifecycle/basic/groovy",files="settings.gradle[];build.gradle[]"]
+====
+
+The following command executes the `test` and `testBoth` tasks specified above.
+Because Gradle only configures requested tasks and their dependencies, the `configured` task never configures:
+
+[source.multi-language-sample,kotlin]
+----
+> gradle test testBoth
+include::{snippetsPath}/buildlifecycle/basic/tests/buildlifecycle.out[]
+----
+[source.multi-language-sample,groovy]
+----
+> gradle test testBoth
+include::{snippetsPath}/buildlifecycle/basic/tests/buildlifecycle.out[]
+----
+
+[[sec:initialization]]
+== Phase 1. Initialization
+
+In the *initialization phase*, Gradle detects the set of projects (root and subprojects) and included builds participating in the build.
+
+Gradle first evaluates the settings file, `settings.gradle(.kts)`, and instantiates a `Settings` object.
+Then, Gradle instantiates `Project` instances for each project.
+
+[[sec:configuration]]
+== Phase 2. Configuration
+
+In the *configuration phase*, Gradle adds tasks and other properties to the projects found by the initialization phase.
+
+[[sec:project_evaluation]]
+[[sec:execution]]
+== Phase 3. Execution
+
+In the *execution phase*, Gradle runs tasks.
+
+Gradle uses the task execution graphs generated by the configuration phase to determine which tasks to execute.
+
+[[sec:task_execution]]
+
+[.text-right]
+**Next Step:** <<writing_settings_files.adoc#writing_settings_files,Learn how to write Settings files>> >>

subprojects/docs/src/docs/userguide/authoring-builds/basics/gradle_directories.adoc

@@ -0,0 +1,110 @@
+// Copyright (C) 2023 Gradle, Inc.
+//
+// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://creativecommons.org/licenses/by-nc-sa/4.0/
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+[[directory_layout]]
+= Gradle Directories
+
+Gradle uses two main directories to perform and manage its work: the <<#dir:gradle_user_home>> and the <<#dir:project_root>>.
+
+image::author-gradle-2.png[]
+
+[[dir:gradle_user_home]]
+== Gradle User Home directory
+
+By default, the Gradle User Home (`~/.gradle` or `C:\Users\<USERNAME>\.gradle`) stores global configuration properties, initialization scripts, caches, and log files.
+
+It can be set with the environment variable `GRADLE_USER_HOME`.
+
+TIP: Not to be confused with the `GRADLE_HOME`, the optional installation directory for Gradle.
+
+It is roughly structured as follows:
+
+[listing]
+----
+├── caches // <1>
+│   ├── 4.8 // <2>
+│   ├── 4.9 // <2>
+│   ├── ⋮
+│   ├── jars-3 // <3>
+│   └── modules-2 // <3>
+├── daemon // <4>
+│   ├── ⋮
+│   ├── 4.8
+│   └── 4.9
+├── init.d // <5>
+│   └── my-setup.gradle
+├── jdks // <6>
+│   ├── ⋮
+│   └── jdk-14.0.2+12
+├── wrapper
+│   └── dists // <7>
+│       ├── ⋮
+│       ├── gradle-4.8-bin
+│       ├── gradle-4.9-all
+│       └── gradle-4.9-bin
+└── gradle.properties // <8>
+----
+<1> Global cache directory (for everything that is not project-specific).
+<2> Version-specific caches (e.g., to support incremental builds).
+<3> Shared caches (e.g., for artifacts of dependencies).
+<4> Registry and logs of the <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>>.
+<5> Global <<init_scripts.adoc#init_scripts, initialization scripts>>.
+<6> JDKs downloaded by the <<toolchains.adoc#sec:provisioning, toolchain support>>.
+<7> Distributions downloaded by the <<gradle_wrapper.adoc#gradle_wrapper,Gradle Wrapper>>.
+<8> Global <<build_environment.adoc#sec:gradle_configuration_properties,Gradle configuration properties>>.
+
+[[dir:project_root]]
+== Project Root directory
+
+The project root directory contains all source files from your project.
+
+It also contains files and directories Gradle generates, such as `.gradle` and `build`.
+
+While `.gradle` is usually checked into source control, the `build` directory contains the output of your builds as well as transient files Gradle uses to support features like incremental builds.
+
+The anatomy of a typical project root directory looks as follows:
+
+[listing,subs=+macros]
+----
+├── .gradle                 // <1>
+│   ├── 4.8                 // <2>
+│   ├── 4.9                 // <2>
+│   └── ⋮
+├── build                   // <3>
+├── gradle
+│   └── wrapper             // <4>
+├── gradle.properties       // <5>
+├── gradlew                 // <6>
+├── gradlew.bat             // <6>
+├── settings.gradle.kts     // <7>
+├── subproject-one          // <8>
+|   └── build.gradle.kts    // <9>
+├── subproject-two          // <8>
+|   └── build.gradle.kts    // <9>
+└── ⋮
+----
+<1> Project-specific cache directory generated by Gradle.
+<2> Version-specific caches (e.g., to support incremental builds).
+<3> The build directory of this project into which Gradle generates all build artifacts.
+<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 <<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.
+
+Consult the <<directory_layout.adoc#directory_layout,Gradle Directories reference>> to learn more.
+
+[.text-right]
+**Next Step:** <<intro_multi_project_builds.adoc#intro_multi_project_builds,Learn how to structure Multi-Project Builds>> >>

subprojects/docs/src/docs/userguide/running-builds/introduction/intro_multi_project_builds.adoc → subprojects/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc

@@ -25,7 +25,7 @@ The word "interdependent" is vital, as you typically want to link the many modul
 Gradle supports this scenario through _multi-project_ builds.
 This is sometimes referred to as a multi-module project.
 
-A multi-project build consists of one root project, and one or more subprojects.
+A multi-project build consists of one root project and one or more subprojects.
 
 [[sec:project_structure]]
 == Multi-Project structure
@@ -40,6 +40,7 @@ The directory structure should look as follows:
 ├── .gradle
 │   └── ⋮
 ├── gradle
+│   ├── libs.version.toml
 │   └── wrapper
 ├── gradlew
 ├── gradlew.bat
@@ -69,11 +70,6 @@ See how to declare <<declaring_dependencies_between_subprojects#declaring_depend
 
 A project path has the following pattern: it starts with an optional colon, which denotes the root project.
 
-[source]
-----
-:
-----
-
 The root project, `:`, is the only project in a path not specified by its name.
 
 The rest of a project path is a colon-separated sequence of project names, where the next project is a subproject of the previous project:
@@ -112,7 +108,7 @@ As an example, let's use a multi-project build with the following structure:
 include::{snippetsPath}/java/multiproject/tests/listProjects.out[]
 ----
 
-From a user's perspective, multi-project builds are collections of tasks you can run.
+Multi-project builds are collections of tasks you can run.
 The difference is that you may want to control _which_ project's tasks get executed.
 
 The following sections will cover your two options for executing tasks in a multi-project build.
@@ -207,3 +203,8 @@ Finally, you can build and test everything in all projects.
 Any task you run in the root project folder will cause that same-named task to be run on all the children.
 
 You can run `gradle build` to build and test ALL projects.
+
+Consult the <<multi_project_builds.adoc#multi_project_builds,Structuring Builds chapter>> to learn more.
+
+[.text-right]
+**Next Step:** <<build_lifecycle.adoc#build_lifecycle,Learn about the Gradle Build Lifecycle>> >>