Merge pull request gradle#26936 Running Gradle Builds section in Grad…

…le User Manual

### Details
This is a Documentation change ONLY.

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

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

#### Please review the finished sections highlighted below:

Running Gradle Builds
- [X] [Getting Started](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74243440:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231108035006%2B0000/docs/userguide/getting_started_eng.html)
- [X] [Core Concepts](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74243440:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231108035006%2B0000/docs/userguide/gradle_basics.html)
- [X] [Tutorial](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74243440:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231108035006%2B0000/docs/userguide/part1_gradle_init.html)
- [X] [Additional Topics](https://builds.gradle.org/repository/download/Gradle_Release_Check_BuildDistributions/74243440:id/distributions/gradle-8.5-docs.zip!/gradle-8.5-20231108035006%2B0000/docs/userguide/gradle_ides.html)

### Notes:
The **Running Gradle Builds** section is for **Developers** that just want to use Gradle (think riding a bike - how to pedal).

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

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

@@ -36,7 +36,7 @@ class AllDistributionIntegrationSpec extends DistributionIntegrationSpec {
 
     @Override
     int getMaxDistributionSizeBytes() {
-        return 206 * 1024 * 1024
+        return 212 * 1024 * 1024
     }
 
     @Requires(UnitTestPreconditions.StableGroovy) // cannot link to public javadocs of Groovy snapshots like https://docs.groovy-lang.org/docs/groovy-4.0.5-SNAPSHOT/html/gapi/

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

@@ -31,7 +31,7 @@ class BinDistributionIntegrationSpec extends DistributionIntegrationSpec {
 
     @Override
     int getMaxDistributionSizeBytes() {
-        return 127 * 1024 * 1024
+        return 128 * 1024 * 1024
     }
 
     def binZipContents() {

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

@@ -32,7 +32,7 @@ class DocsDistributionIntegrationSpec extends DistributionIntegrationSpec {
 
     @Override
     int getMaxDistributionSizeBytes() {
-        return 74 * 1024 * 1024
+        return 84 * 1024 * 1024
     }
 
     @Override

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

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

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

@@ -15,9 +15,9 @@
  */
  /* Custom Admonition Blocks */
 :root {
-    --caution-color: #802392;
+    --caution-color: #e40046;
     --caution-on-color: #fff;
-    --important-color: #e40046;
+    --important-color: #802392;
     --important-on-color: #fff;
     --note-color: #2d7dd2;
     --note-on-color: #fff;
@@ -285,6 +285,8 @@ small { font-size: 60%; line-height: inherit; }
 
 code { font-family: "Droid Sans Mono", "DejaVu Sans Mono", monospace; font-weight: normal; color: rgba(0, 0, 0, 0.9); }
 
+a code { color: #021274; }
+
 /* Lists */
 ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }
 
@@ -785,7 +787,7 @@ td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }
 
 td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }
 
-.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
+.literalblock + .colist { margin-top: -0.5em; }
 
 .colist > table tr > td:first-of-type { padding: 0 0.75em; line-height: 1; }
 .colist > table tr > td:first-of-type img { max-width: initial; }
@@ -991,6 +993,7 @@ a:focus {
 }
 
 #content a[href^='../dsl/'],
+#content a[href^='../kotlin-dsl/'],
 #content a[href^='../javadoc/'] {
     font-family: 'Inconsolata', monospace;
     font-style: normal;
@@ -1000,6 +1003,8 @@ a:focus {
 
 #content a[href^='../dsl/']:hover,
 #content a[href^='../dsl/']:focus,
+#content a[href^='../kotlin-dsl/']:hover,
+#content a[href^='../kotlin-dsl/']:focus,
 #content a[href^='../javadoc/']:hover,
 #content a[href^='../javadoc/']:focus {
     text-decoration: none;

subprojects/docs/src/docs/userguide/running-builds/build_environment.adoc → subprojects/docs/src/docs/userguide/authoring-builds/build_environment.adoc

@@ -47,7 +47,7 @@ When configuring Gradle behavior, you can use these methods, listed in order of
 |3.2
 |<<#sec:gradle_configuration_properties, Gradle properties>>
 |`org.gradle.caching=true`
-|Stored in a `gradle.properties` file in the <<sec:gradle_environment_variables,GRADLE_HOME>>.
+|Stored in a `gradle.properties` file in the `<<sec:gradle_environment_variables,GRADLE_HOME>>`.
 
 |4
 |<<#sec:gradle_environment_variables, Environment variables>>

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

@@ -22,7 +22,7 @@ It uses toy examples to explain basic functionality of Gradle, which is helpful
 Especially if you move to Gradle from other build tools like Ant and want to understand differences and advantages.
 
 However, to get started with a standard project setup, you don't even need to go into these concepts in detail.
-Instead, you can have a quick hands-on introduction, through our <<introduction.adoc#getting_started,step-by-step tutorial>>.
+Instead, you can have a quick hands-on introduction, through our <<getting_started_eng.adoc#getting_started,step-by-step tutorial>>.
 
 [[sec:projects_and_tasks]]
 == Projects, plugins and tasks

subprojects/docs/src/docs/userguide/optimizing-performance/gradle_daemon.adoc

@@ -104,7 +104,7 @@ org.gradle.daemon=true
 
 You can disable the Daemon in multiple ways but there are important considerations:
 
-Single-use Deamon :: If the JVM args of the client process don't match what the build requires, a single-used Daemon (disposable JVM) is created.
+Single-use Daemon :: If the JVM args of the client process don't match what the build requires, a single-used Daemon (disposable JVM) is created.
 This means the Daemon is required for the build, so it is created, used, and then stopped at the end of the build.
 
 No Daemon :: If the `JAVA_OPTS` and `GRADLE_OPTS` match `org.gradle.jvmargs`, the Daemon will not be used at all since the build happens in the client JVM.

subprojects/docs/src/docs/userguide/overview/about_manual.adoc

@@ -17,13 +17,17 @@
 
 Explore our guides and examples to use Gradle.
 
+[[releases]]
+== Releases
+
+Information on Gradle releases and how to install Gradle is found on the <<installation.adoc#installation,Installation page>>.
+
 [[content]]
 == Content
 
 The Gradle User Manual is broken down into the following sections:
 
-<<introduction#introduction,Getting Started>> :: Installing Gradle and learn the basics with our getting started tutorial.
-<<command_line_interface.adoc#command_line_interface,Running Gradle Builds>> :: Learn how to use Gradle to build your project.
+<<command_line_interface.adoc#command_line_interface,Running Gradle Builds>> :: Learn Gradle basics and how to use Gradle to build your project.
 <<build_lifecycle.adoc#build_lifecycle,Authoring Gradle Builds>> :: Develop tasks and plugins to customize your build.
 <<building_java_projects.adoc#building_java_projects,Authoring JVM Builds>> :: Use Gradle with your Java project.
 <<dependency_management_terminology.adoc#dependency_management_terminology,Working with Dependencies>> :: Add dependencies to your build.

subprojects/docs/src/docs/userguide/overview/userguide.adoc

@@ -51,7 +51,7 @@ You can also invoke Gradle via its <<command_line_interface.adoc#command_line_in
 == Education
 The **<<about_manual.adoc#about_manual,Gradle User Manual>>** is the official documentation for the Gradle Build Tool.
 
-* **Getting Started Tutorial** — <<introduction#introduction,Learn Gradle basics>> and the benefits of building your App with Gradle.
+* **Getting Started Tutorial** — <<getting_started_eng.adoc#introduction,Learn Gradle basics>> and the benefits of building your App with Gradle.
 * **Training Courses** — Head over to the link:https://gradle.org/courses/[courses page] to sign up for free Gradle training.
 
 == Support

subprojects/docs/src/docs/userguide/running-builds/command_line_interface.adoc → subprojects/docs/src/docs/userguide/reference/command_line_interface.adoc

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 [[command_line_interface]]
-= Command-Line Interface
+= Command-Line Interface Reference
 
 The command-line interface is the **primary method of interacting with Gradle**.
 

subprojects/docs/src/docs/userguide/running-builds/gradle_wrapper.adoc → subprojects/docs/src/docs/userguide/reference/gradle_wrapper.adoc

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 [[gradle_wrapper]]
-= Gradle Wrapper
+= Gradle Wrapper Reference
 
 The **recommended way to execute any Gradle build** is with the help of the Gradle Wrapper (referred to as "Wrapper").
 

subprojects/docs/src/docs/userguide/getting-started/installation.adoc → subprojects/docs/src/docs/userguide/releases/installation.adoc

@@ -15,6 +15,14 @@
 [[installation]]
 = Installing Gradle
 
+[[gs:installation]]
+== Gradle Installation
+If all you want to do is run an existing Gradle build, then you don't need to install Gradle if the build uses the <<gradle_wrapper#gradle_wrapper,Gradle Wrapper>>.
+This is identifiable by the presence of the `gradlew` or `gradlew.bat` files in the root of the build.
+You just need to make sure your system <<installation#sec:prerequisites,satisfies Gradle's prerequisites>>.
+
+Android Studio comes with a working installation of Gradle, so you don't need to install Gradle separately when only working within that IDE.
+
 You can install Gradle Build Tool on Linux, macOS, or Windows.
 
 The installation can be done manually or using a package manager like https://sdkman.io/[SDKMAN!] or https://brew.sh/[Homebrew].
@@ -227,7 +235,7 @@ We recommend downloading the bin file.
 Create a new directory `C:\Gradle` with **File Explorer**.
 
 Open a second **File Explorer** window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content.
-Drag the `gradle-{gradleVersion}` directory to your newly created `C:\Gradle` folder.
+Drag the content folder `gradle-{gradleVersion}` to your newly created `C:\Gradle` folder.
 
 Alternatively, you can unpack the Gradle distribution ZIP into `C:\Gradle` using the archiver tool of your choice.
 

subprojects/docs/src/docs/userguide/running-builds/additional/continuous_build.adoc

@@ -0,0 +1,76 @@
+// 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.
+
+[[continous_build]]
+= Continuous Build
+
+Continuous Build allows you to automatically re-execute the requested tasks when file inputs change.
+You can execute the build in this mode using the `-t` or `--continuous` command-line option.
+
+For example, you can continuously run the `test` task and all dependent tasks by running:
+
+----
+$ gradle test --continuous
+----
+
+Gradle will behave as if you ran `gradle test` after a change to sources or tests that contribute to the requested tasks.
+This means unrelated changes (such as changes to build scripts) will not trigger a rebuild.
+To incorporate build logic changes, the continuous build must be restarted manually.
+
+Continuous build uses <<file_system_watching.adoc#sec:daemon_watch_fs,file system watching>> to detect changes to the inputs.
+If file system watching does not work on your system, then continuous build won't work either.
+In particular, continuous build does not work when using `--no-daemon`.
+
+When Gradle detects a change to the inputs, it will not trigger the build immediately.
+Instead, it will wait until no additional changes are detected for a certain period of time - the quiet period.
+You can configure the quiet period in milliseconds by the Gradle property `<<build_environment.adoc#sec:gradle_configuration_properties,org.gradle.continuous.quietperiod>>`.
+
+== Terminating Continuous Build
+If Gradle is attached to an interactive input source, such as a terminal, the continuous build can be exited by pressing `CTRL-D` (On Microsoft Windows, it is required to also press `ENTER` or `RETURN` after `CTRL-D`).
+
+If Gradle is not attached to an interactive input source (e.g. is running as part of a script), the build process must be terminated (e.g. using the `kill` command or similar).
+
+If the build is being executed via the Tooling API, the build can be cancelled using the Tooling API's cancellation mechanism.
+
+[[continuous_build_limitations]]
+== Limitations
+Under some circumstances, continuous build may not detect changes to inputs.
+
+[[sec:continuous_build_missing_files]]
+=== Creating input directories
+Sometimes, creating an input directory that was previously missing does not trigger a build, due to the way file system watching works.
+For example, creating the `src/main/java` directory may not trigger a build.
+Similarly, if the input is a <<working_with_files.adoc#filtering_files,filtered file tree>> and no files are matching the filter, the creation of matching files may not trigger a build.
+
+[[sec:continuous_build_untracked]]
+=== Inputs of untracked tasks
+Changes to the inputs of <<incremental_build.adoc#sec:disable-state-tracking,untracked tasks>> or tasks that have no outputs may not trigger a build.
+
+[[sec:continuous_build_project_dir]]
+=== Changes to files outside of project directories
+Gradle only watches for changes to files inside the project directory.
+Changes to files outside the project directory will go undetected and not trigger a build.
+
+[[sec:build_cycles]]
+=== Build cycles
+Gradle starts watching for changes just before a task executes.
+If a task modifies its own inputs while executing, Gradle will detect the change and trigger a new build.
+If every time the task executes, the inputs are modified again, the build will be triggered again.
+This isn't unique to continuous build.
+A task that modifies its own inputs will never be considered up-to-date when run "normally" without continuous build.
+
+If your build enters a build cycle like this, you can track down the task by looking at the list of files reported changed by Gradle.
+After identifying the file(s) that are changed during each build, you should look for a task that has that file as an input.
+In some cases, it may be obvious (e.g., a Java file is compiled with `compileJava`).
+In other cases, you can use `--info` logging to find the task that is out-of-date due to the identified files.

subprojects/docs/src/docs/userguide/running-builds/additional/gradle_ides.adoc

@@ -0,0 +1,67 @@
+// 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.
+
+[[gradle_ides]]
+= Gradle in IDEs
+
+Many IDEs support Gradle including Android Studio, IntelliJ IDEA, Visual Studio Code, Eclipse, and NetBeans.
+
+== IntelliJ IDEA
+
+IntelliJ IDEA supports a fully-functional integration with Gradle that helps you automate your building process.
+
+image::intellij_idea.png[]
+
+You can easily create a new Gradle project, open and sync an existing one, work with several linked projects simultaneously, and manage them.
+
+You can find documentation link:https://www.jetbrains.com/help/idea/gradle.html[here].
+
+== Android Studio
+
+Android Studio is the official IDE for Android app development, based on IntelliJ IDEA.
+
+Android Studio uses Gradle to automate and manage the build process while letting you define flexible, custom build configurations.
+
+image::android_studio.png[]
+
+You can find documentation link:https://developer.android.com/build[here].
+
+== Visual Studio Code
+
+VS Code supports Gradle Java projects (not including Android) via the link:https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle[Gradle for Java extension].
+
+image::visual_studio_code.png[]
+
+The extension provides a visual interface for your Gradle build.
+You can use this interface to view Gradle Tasks and Project dependencies, or run Gradle Tasks as VS Code Tasks. The extension also offers a better Gradle build file authoring experience including syntax highlighting, error reporting, and auto-completion.
+
+You can find documentation link:https://code.visualstudio.com/docs/java/java-build[here].
+
+== Eclipse
+
+The Eclipse IDE caters to the Java developer, and features Java tooling, a Git client, XML Editor, and Gradle integration.
+
+image::eclipse.png[]
+
+link:https://marketplace.eclipse.org/content/buildship-gradle-integration[Buildship] is a set of Eclipse Plug-ins that provide a deep integration of Gradle into the Eclipse IDE.
+
+You can find documentation link:https://projects.eclipse.org/projects/tools.buildship[here].
+
+== NetBeans
+
+The Apache Software Foundation maintains NetBeans, an open-source IDE for Java, PHP, Javascript and other languages.
+
+image::netbeans.png[]
+
+You can find documentation link:https://cwiki.apache.org/confluence/display/BEAM/Gradle+Tips[here].

subprojects/docs/src/docs/userguide/getting-started/introduction.adoc → subprojects/docs/src/docs/userguide/running-builds/getting_started_eng.adoc

@@ -13,25 +13,44 @@
 // limitations under the License.
 
 [[introduction]]
-= Introduction
+= Getting Started
 
 Everyone has to start somewhere, and if you're new to Gradle, this is where to begin.
 
-[[gs:installation]]
-== Gradle Installation
-If all you want to do is run an existing Gradle build, then you don't need to install Gradle if the build uses the <<gradle_wrapper#gradle_wrapper,Gradle Wrapper>>.
-This is identifiable by the presence of the `gradlew` or `gradlew.bat` files in the root of the build.
-You just need to make sure your system <<installation#sec:prerequisites,satisfies Gradle's prerequisites>>.
+To get started using Gradle:
 
-Android Studio comes with a working installation of Gradle, so you don't need to install Gradle separately when only working within that IDE.
+1. Read the <<gradle_intro,core concepts chapters>>.
+2. Follow the <<getting_started,tutorial>> for a hands-on approach.
 
-To create a new build or add a Wrapper to an existing build, you will need to install Gradle <<installation.adoc#installation,according to these instructions>>.
+[[gradle_intro]]
+== 1. Gradle Core Concepts
 
-If you need to install Gradle before the tutorial, you can do so in the <<installation.adoc#installation,installation section>>.
+The core concepts section goes through the Gradle basics so that you can quickly understand how to invoke tasks, turn on features, apply plugins, add dependencies to your project, and more.
+
+[sidebar]
+_Training level_: **Beginner** +
+_Reading time_: **25 minutes**
+
+The core concepts cover:
+
+<<gradle_basics.adoc#gradle,Part 1.>> Gradle Overview +
+<<gradle_wrapper_basics.adoc#gradle_wrapper,Part 2.>> Gradle's Wrapper +
+<<command_line_interface_basics.adoc#command_line_interface,Part 3.>> Gradle's Command Line Interface +
+<<settings_file_basics.adoc#settings_file_basics,Part 4.>> Settings File +
+<<build_file_basics.adoc#build_file_basics,Part 5.>> Build Files +
+<<dependency_management_basics.adoc#dependency_management_basics,Part 6.>> Dependency Management +
+<<task_basics.adoc#task_basics,Part 7.>> Tasks +
+<<plugin_basics.adoc#plugin_basics,Part 8.>> Plugins +
+<<build_scans.adoc#build_scans,Part 9.>> Build Scans +
+<<gradle_optimizations.adoc#gradle_optimizations,Part 10.>> Gradle Optimizations +
 
 [[getting_started]]
-== Getting Started with Gradle
-The tutorial will take you from Gradle initialization all the way through to utilizing Gradle's task caching for your basic Java App. No previous experience is necessary but a basic knowledge of Java and Kotlin is nice to have.
+== 2. Gradle Tutorial
+
+The tutorial will take you from Gradle initialization all the way through to utilizing Gradle's task caching for your basic Java App.
+No previous experience is necessary but a basic knowledge of Java and Kotlin is nice to have.
+
+If you need to install Gradle before the tutorial, you can do so in the <<installation.adoc#installation,installation section>>.
 
 [sidebar]
 _Training level_: **Beginner** +