Codestin Search App

By entering your email, you agree to our Terms and Privacy Policy, including receipt of emails. You can unsubscribe at any time.

diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc index d40f9548f9b6e..4242ddff64631 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/basics/intro_multi_project_builds.adoc @@ -256,7 +256,7 @@ The `build` task is typically used to compile, test, and check a single project. In multi-project builds, you may often want to do all of these tasks across various projects. The `buildNeeded` and `buildDependents` tasks can help with this. -In <>, the `:services:person-service` project depends on both the `:api` and `:shared` projects. +In <>, the `:services:person-service` project depends on both the `:api` and `:shared` projects. The `:api` project also depends on the `:shared` project. Assuming you are working on a single project, the `:api` project, you have been making changes but have not built the entire project since performing a `clean`. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/best-practices/organizing_gradle_projects.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/best-practices/organizing_gradle_projects.adoc deleted file mode 100644 index 6bf36274423d5..0000000000000 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/best-practices/organizing_gradle_projects.adoc +++ /dev/null @@ -1,302 +0,0 @@ -// Copyright (C) 2024 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. - -[[organizing_gradle_projects]] -= Organizing Gradle Projects - -Source code and build logic of every software project should be organized in a meaningful way. -This page lays out the best practices that lead to readable, maintainable projects. -The following sections also touch on common problems and how to avoid them. - -[[sec:separate_language_source_files]] -== Separate language-specific source files - -Gradle's language plugins establish conventions for discovering and compiling source code. -For example, a project applying the <> will automatically compile the code in the directory `src/main/java`. -Other language plugins follow the same pattern. -The last portion of the directory path usually indicates the expected language of the source files. - -Some compilers are capable of cross-compiling multiple languages in the same source directory. -The Groovy compiler can handle the scenario of mixing Java and Groovy source files located in `src/main/groovy`. -Gradle recommends that you place sources in directories according to their language, because builds are more performant and both the user and build can make stronger assumptions. - -The following source tree contains Java and Kotlin source files. Java source files live in `src/main/java`, whereas Kotlin source files live in `src/main/kotlin`. - -==== -[.multi-language-sample] -===== -[source,kotlin] ----- -. -├── build.gradle.kts -└── src - └── main - ├── java - │ └── HelloWorld.java - └── kotlin - └── Utils.kt ----- -===== -[.multi-language-sample] -===== -[source,groovy] ----- -. -├── build.gradle -└── src - └── main - ├── java - │ └── HelloWorld.java - └── kotlin - └── Utils.kt ----- -===== -==== - -[[sec:separate_test_type_source_files]] -== Separate source files per test type - -It's very common that a project defines and executes different types of tests e.g. unit tests, integration tests, functional tests or smoke tests. -Optimally, the test source code for each test type should be stored in dedicated source directories. -Separated test source code has a positive impact on maintainability and separation of concerns as you can run test types independent from each other. - -Have a look at the link:../samples/sample_jvm_multi_project_with_additional_test_types.html[sample] -that demonstrates how a separate integration tests configuration can be added to a Java-based project. - -[[sec:use_standard_conventions]] -== Use standard conventions as much as possible - -All Gradle core plugins follow the software engineering paradigm link:https://en.wikipedia.org/wiki/Convention_over_configuration[convention over configuration]. -The plugin logic provides users with sensible defaults and standards, the conventions, in a certain context. -Let’s take the <> as an example. - -* It defines the directory `src/main/java` as the default source directory for compilation. -* The output directory for compiled source code and other artifacts (like the JAR file) is `build`. - -By sticking to the default conventions, new developers to the project immediately know how to find their way around. -While those conventions can be reconfigured, it makes it harder to build script users and authors to manage the build logic and its outcome. -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. -The file can either be empty or define the desired name of the project. - -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 <>. -Besides defining included projects, you might need it to <>. - -The following example shows a standard Gradle project layout: - -==== -[.multi-language-sample] -===== -[source,kotlin] ----- -. -├── settings.gradle.kts -├── subproject-one -│ └── build.gradle.kts -└── subproject-two - └── build.gradle.kts ----- -===== -[.multi-language-sample] -===== -[source,groovy] ----- -. -├── settings.gradle -├── subproject-one -│ └── build.gradle -└── subproject-two - └── build.gradle ----- -===== -==== - -[[sec:build_sources]] -== Use `buildSrc` to abstract imperative logic - -Complex build logic is usually a good candidate for being encapsulated either as custom task or binary plugin. -Custom task and plugin implementations should not live in the build script. -It is very convenient to use `buildSrc` for that purpose as long as the code does not need to be shared among multiple, independent projects. - -The directory `buildSrc` is treated as an <>. Upon discovery of the directory, Gradle automatically compiles this code and puts it in the classpath of your build script. -For multi-project builds there can be only one `buildSrc` directory, which has to sit in the root project directory. -`buildSrc` should be preferred over <> as it is easier to maintain, refactor and test the code. - -`buildSrc` uses the same <> applicable to Java and Groovy projects. -It also provides direct access to the Gradle API. Additional dependencies can be declared in a dedicated `build.gradle` under `buildSrc`. - -.Custom buildSrc build script -==== -include::sample[dir="snippets/java/multiproject/kotlin",files="buildSrc/build.gradle.kts[]"] -include::sample[dir="snippets/java/multiproject/groovy",files="buildSrc/build.gradle[]"] -==== - -A typical project including `buildSrc` has the following layout. -Any code under `buildSrc` should use a package similar to application code. -Optionally, the `buildSrc` directory can host a build script if additional configuration is needed (e.g. to apply plugins or to declare dependencies). - -==== -[.multi-language-sample] -===== -[source,kotlin] ----- -. -├── buildSrc -│ ├── build.gradle.kts -│ └── src -│ ├── main -│ │ └── java -│ │ └── com -│ │ └── enterprise -│ │ ├── Deploy.java -│ │ └── DeploymentPlugin.java -│ └── test -│ └── java -│ └── com -│ └── enterprise -│ └── DeploymentPluginTest.java -├── settings.gradle.kts -├── subproject-one -│ └── build.gradle.kts -└── subproject-two - └── build.gradle.kts ----- -===== -[.multi-language-sample] -===== -[source,groovy] ----- -. -├── buildSrc -│ ├── build.gradle -│ └── src -│ ├── main -│ │ └── java -│ │ └── com -│ │ └── enterprise -│ │ ├── Deploy.java -│ │ └── DeploymentPlugin.java -│ └── test -│ └── java -│ └── com -│ └── enterprise -│ └── DeploymentPluginTest.java -├── settings.gradle -├── subproject-one -│ └── build.gradle -└── subproject-two - └── build.gradle ----- -===== -==== - -[NOTE] -==== -A change in `buildSrc` causes the whole project to become out-of-date. - -Thus, when making small incremental changes, the <> is often helpful to get faster feedback. -Remember to run a full build regularly. -==== - -== Declare properties in `gradle.properties` file - -In Gradle, properties can be defined in the build script, in a `gradle.properties` file or as parameters on the command line. - -It's common to declare properties on the command line for ad-hoc scenarios. -For example you may want to pass in a specific property value to control runtime behavior just for this one invocation of the build. -Properties in a build script can easily become a maintenance headache and convolute the build script logic. -The `gradle.properties` helps with keeping properties separate from the build script and should be explored as viable option. -It's a good location for placing <>. - -A typical project setup places the `gradle.properties` file in the root directory of the build. -Alternatively, the file can also live in the `<>` directory if you want it to apply to all builds on your machine. - -==== -[.multi-language-sample] -===== -[source,kotlin] ----- -. -├── gradle.properties -└── settings.gradle.kts -├── subproject-a -│ └── build.gradle.kts -└── subproject-b - └── build.gradle.kts ----- -===== -[.multi-language-sample] -===== -[source,groovy] ----- -. -├── gradle.properties -└── settings.gradle -├── subproject-a -│ └── build.gradle -└── subproject-b - └── build.gradle ----- -===== -==== - -== Avoid overlapping task outputs - -Tasks should define inputs and outputs to get the performance benefits of <>. -When declaring the outputs of a task, make sure that the directory for writing outputs is unique among all the tasks in your project. - -Intermingling or overwriting output files produced by different tasks compromises up-to-date checking causing slower builds. -In turn, these filesystem changes may prevent Gradle's <> from properly identifying and caching what would otherwise be cacheable tasks. - -[[sec:custom_gradle_distribution]] -== Standardizing builds with a custom Gradle distribution - -Often enterprises want to standardize the build platform for all projects in the organization by defining common conventions or rules. -You can achieve that with the help of initialization scripts. -<> make it extremely easy to apply build logic across all projects on a single machine. -For example, to declare a in-house repository and its credentials. - -There are some drawbacks to the approach. -First of all, you will have to communicate the setup process across all developers in the company. -Furthermore, updating the initialization script logic uniformly can prove challenging. - -Custom Gradle distributions are a practical solution to this very problem. -A custom Gradle distribution is comprised of the standard Gradle distribution plus one or many custom initialization scripts. -The initialization scripts come bundled with the distribution and are applied every time the build is run. -Developers only need to point their checked-in <> files to the URL of the custom Gradle distribution. - -Custom Gradle distributions may also contain a `gradle.properties` file in the root of the distribution, which provide an organization-wide <>. - -The following steps are typical for creating a custom Gradle distribution: - -1. Implement logic for downloading and repackaging a Gradle distribution. -2. Define one or many initialization scripts with the desired logic. -3. Bundle the initialization scripts with the Gradle distribution. -4. Upload the Gradle distribution archive to a HTTP server. -5. Change the Wrapper files of all projects to point to the URL of the custom Gradle distribution. - -.Building a custom Gradle distribution -==== -include::sample[dir="snippets/organizingGradleProjects/customGradleDistribution/groovy",files="build.gradle[]"] -==== diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/collections.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/collections.adoc index c320c24595528..0b326d696e6e2 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/collections.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/collections.adoc @@ -35,7 +35,7 @@ These collection types are used for managing collections of objects, particularl These types are commonly used in Gradle plugins and build scripts to manage collections of objects, such as tasks, configurations, or custom domain objects. [[domainobjectset]] -== 1. `DomainObjectSet` +== `DomainObjectSet` A link:{javadocPath}/org/gradle/api/DomainObjectSet.html[`DomainObjectSet`] simply holds a set of configurable objects. @@ -50,7 +50,7 @@ include::sample[dir="snippets/providers/collections/groovy",files="build.gradle[ ==== [[nameddomainobjectset]] -== 2. `NamedDomainObjectSet` +== `NamedDomainObjectSet` A link:{javadocPath}/org/gradle/api/NamedDomainObjectSet.html[`NamedDomainObjectSet`] holds a set of configurable objects, where each element has a name associated with it. @@ -65,7 +65,7 @@ include::sample[dir="snippets/providers/collections/groovy",files="build.gradle[ ==== [[nameddomainobjectlist]] -== 3. `NamedDomainObjectList` +== `NamedDomainObjectList` A link:{javadocPath}/org/gradle/api/NamedDomainObjectList.html[`NamedDomainObjectList`] holds a list of configurable objects, where each element has a name associated with it. @@ -80,7 +80,7 @@ include::sample[dir="snippets/providers/collections/groovy",files="build.gradle[ ==== [[nameddomainobjectcontainer]] -== 4. `NamedDomainObjectContainer` +== `NamedDomainObjectContainer` A link:{javadocPath}/org/gradle/api/NamedDomainObjectContainer.html[`NamedDomainObjectContainer`] manages a set of objects, where each element has a name associated with it. @@ -133,7 +133,7 @@ include::{snippetsPath}/plugins/namedDomainObjectContainer/groovy/build.gradle[] ==== [[extensiblepolymorphicdomainobjectcontainer]] -== 5. `ExtensiblePolymorphicDomainObjectContainer` +== `ExtensiblePolymorphicDomainObjectContainer` An link:{javadocPath}/org/gradle/api/ExtensiblePolymorphicDomainObjectContainer.html[ExtensiblePolymorphicDomainObjectContainer] is a `NamedDomainObjectContainer` that allows you to define instantiation strategies for different types of objects. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/properties_providers.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/properties_providers.adoc index 27ce5a3049524..f655ebbc3722e 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/properties_providers.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/properties_providers.adoc @@ -14,6 +14,7 @@ [[properties_and_providers]] = Understanding Properties and Providers +:keywords: properties, providers, regularfileproperty, directoryproperty, listproperty, setproperty, mapproperty, configurablefilecollection, configurablefiletree Gradle provides properties that are important for <>. When implementing a custom task or plugin, it's imperative that you use these lazy properties. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/service_injection.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/service_injection.adoc index 42f90a3adc237..4e1edc2972797 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/service_injection.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/service_injection.adoc @@ -13,8 +13,8 @@ // limitations under the License. [[service_injection]] -= Understanding Services and Service Injection -:keywords: services,service,injection,inject += Services and Service Injection +:keywords: services, service, injection, inject, objectfactory, providerfactory, workerexecutor, archiveoperations, execoperations, toolingmodelbuilderregistry, testeventreporterfactory Gradle provides a number of useful services that can be used by custom Gradle types. For example, the link:{javadocPath}/org/gradle/workers/WorkerExecutor.html[WorkerExecutor] service can be used by a task to run work in parallel, as seen in the <> section. @@ -46,7 +46,7 @@ Only inject the services explicitly listed above to ensure stability and compati WARNING: You should avoid injecting types not listed above. [[objectfactory]] -== 1. `ObjectFactory` +== `ObjectFactory` link:{javadocPath}/org/gradle/api/model/ObjectFactory.html[`ObjectFactory`] is a service for creating custom Gradle types, allowing you to define nested objects and DSLs in your build logic. It provides methods for creating instances of different types, such as properties (`Property`), collections (`ListProperty`, `SetProperty`, `MapProperty`), file-related objects (`RegularFileProperty`, `DirectoryProperty`, `ConfigurableFileCollection`, `ConfigurableFileTree`), and more. @@ -84,7 +84,7 @@ include::sample[dir="snippets/providers/services/groovy",files="build.gradle[tag The `MyObjectFactoryTask` task uses an `ObjectFactory` instance, which is injected into the task's constructor using the `@Inject` annotation. [[sec:projectlayout]] -== 2. `ProjectLayout` +== `ProjectLayout` link:{groovyDslPath}/org.gradle.api.file.ProjectLayout.html[`ProjectLayout`] is a service that provides access to the layout of a Gradle project's directories and files. It's part of the `org.gradle.api.file` package and allows you to query the project's layout to get information about source sets, build directories, and other file-related aspects of the project. @@ -107,7 +107,7 @@ include::sample[dir="snippets/providers/services/groovy",files="build.gradle[tag The `MyProjectLayoutTask` task uses a `ProjectLayout` instance, which is injected into the task's constructor using the `@Inject` annotation. [[buildlayout]] -== 3. `BuildLayout` +== `BuildLayout` link:{groovyDslPath}/org.gradle.api.file.BuildLayout.html[`BuildLayout`] is a service that provides access to the root and settings directory in a Settings plugin or a Settings script, it is analogous to `ProjectLayout`. It's part of the `org.gradle.api.file` package to access standard build-wide file system locations as lazily computed value. @@ -135,7 +135,7 @@ This code defines a `MyBuildLayoutPlugin` plugin that implements the `Plugin` in The plugin expects a `BuildLayout` instance to be injected into its constructor using the `@Inject` annotation. [[providerfactory]] -== 4. `ProviderFactory` +== `ProviderFactory` link:{groovyDslPath}/org.gradle.api.provider.ProviderFactory.html[`ProviderFactory`] is a service that provides methods for creating different types of providers. Providers are used to model values that may be computed lazily in your build scripts. @@ -166,7 +166,7 @@ include::sample[dir="snippets/providers/services/groovy",files="build.gradle[tag The `ProviderFactory` service is injected into the `MyProviderFactoryTask` task's constructor using the `@Inject` annotation. [[workerexecutor]] -== 5. `WorkerExecutor` +== `WorkerExecutor` link:{javadocPath}/org/gradle/workers/WorkerExecutor.html[`WorkerExecutor`] is a service that allows you to perform parallel execution of tasks using worker processes. This is particularly useful for tasks that perform CPU-intensive or long-running operations, as it allows them to be executed in parallel, improving build performance. @@ -184,7 +184,7 @@ include::sample[dir="snippets/providers/services/groovy",files="build.gradle[tag See <> for more details. [[filesystemoperations]] -== 6. `FileSystemOperations` +== `FileSystemOperations` link:{javadocPath}/org/gradle/api/file/FileSystemOperations.html[`FileSystemOperations`] is a service that provides methods for performing file system operations such as copying, deleting, and syncing. It is part of the `org.gradle.api.file` package and is typically used in custom tasks or plugins to interact with the file system. @@ -211,7 +211,7 @@ Then call the method link:{javadocPath}/org/gradle/api/model/ObjectFactory.html# TIP: This is a good time to consider extracting the ad-hoc task into a proper class. [[archiveoperations]] -== 7. `ArchiveOperations` +== `ArchiveOperations` link:{javadocPath}/org/gradle/api/file/ArchiveOperations.html[`ArchiveOperations`] is a service that provides methods for accessing the contents of archives, such as ZIP and TAR files. It is part of the `org.gradle.api.file` package and is typically used in custom tasks or plugins to unpack archive files. @@ -238,7 +238,7 @@ Then call the method link:{javadocPath}/org/gradle/api/model/ObjectFactory.html# TIP: This is a good time to consider extracting the ad-hoc task into a proper class. [[execoperations]] -== 8. `ExecOperations` +== `ExecOperations` link:{javadocPath}/org/gradle/process/ExecOperations.html[`ExecOperations`] is a service that provides methods for executing external processes (commands) from within a build script. It is part of the `org.gradle.process` package and is typically used in custom tasks or plugins to run command-line tools or scripts as part of the build process. @@ -265,7 +265,7 @@ Then call the method link:{javadocPath}/org/gradle/api/model/ObjectFactory.html# TIP: This is a good time to consider extracting the ad-hoc task into a proper class. [[toolingmodelbuilderregistry]] -== 9. `ToolingModelBuilderRegistry` +== `ToolingModelBuilderRegistry` link:{javadocPath}/org/gradle/tooling/provider/model/ToolingModelBuilderRegistry.html[`ToolingModelBuilderRegistry`] is a service that allows you to register custom tooling model builders. Tooling models are used to provide rich IDE integration for Gradle projects, allowing IDEs to understand and work with the project's structure, dependencies, and other aspects. @@ -282,7 +282,7 @@ include::sample[dir="snippets/providers/services/groovy",files="build.gradle[tag You can learn more at <>. [[testeventreporterfactory]] -== 10. `TestEventReporterFactory` +== `TestEventReporterFactory` WARNING: This API is incubating. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/working_with_files.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/working_with_files.adoc index 6d15707efdc88..a86c3d0a0b589 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/working_with_files.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/gradle-properties/working_with_files.adoc @@ -14,6 +14,7 @@ [[working_with_files]] = Working With Files +:keywords: projectlayout, project.file, filecollection, project.copy, filetree, archiveFileName, archiveFile, destinationDirectory, archiveBaseName, archiveAppendix, archiveVersion, archiveClassifier, archiveExtension File operations are fundamental to nearly every Gradle build. They involve handling source files, managing file dependencies, and generating reports. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/dataflow_actions.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/dataflow_actions.adoc index fd50c0e556bd5..1e99ad2a7e71d 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/dataflow_actions.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/dataflow_actions.adoc @@ -14,6 +14,7 @@ [[dataflow_action]] = Dataflow Actions +:keywords: flowaction, flowprovider NOTE: The dataflow actions support is an <> feature and is subject to change. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/init_scripts.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/init_scripts.adoc index 8c1b08ad8838f..91a0c4da9007f 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/init_scripts.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/other/init_scripts.adoc @@ -14,6 +14,7 @@ [[init_scripts]] = Initialization Scripts +:keywords: init, init.gradle Initialization scripts are scripts that run before the build script is executed. They allow you to customize the build environment or configure settings early in the build. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins.adoc index 5c8465ea987b3..edb937a40063e 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins.adoc @@ -13,7 +13,7 @@ // limitations under the License. [[implemention_plugins]] -= Understanding Implementation Options for Plugins += Implementation Options for Plugins The choice between script, precompiled script, or binary plugins depends on your specific requirements and preferences. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_binary.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_binary.adoc index 51e3cd564698c..a3c5f55bb4b0f 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_binary.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_binary.adoc @@ -14,6 +14,7 @@ [[implemention_binary_plugins]] = Implementing Binary Plugins +:keywords: binary, plugin *Binary plugins* refer to plugins that are compiled and distributed as JAR files. These plugins are usually written in Java or Kotlin and provide custom functionality or tasks to a Gradle build. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_precompiled.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_precompiled.adoc index 360d699448945..9ea24e8a8587a 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_precompiled.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/implementing_gradle_plugins_precompiled.adoc @@ -14,6 +14,7 @@ [[implemention_precompiled_plugins]] = Implementing Pre-compiled Script Plugins +:keywords: precompiled, plugin A *precompiled script plugin* is typically a Kotlin script that has been compiled and distributed as Java class files packaged in a library. These scripts are intended to be consumed as binary Gradle plugins and are recommended for use as convention plugins. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/publishing_gradle_plugins.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/publishing_gradle_plugins.adoc index 560a5391c5961..a87cdee757e83 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/publishing_gradle_plugins.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/publishing_gradle_plugins.adoc @@ -18,6 +18,7 @@ :plugin: Greeting Plugin :publishplugin: Plugin Publishing Plugin :plugin-reference-documentation: https://plugins.gradle.org/docs/publish-plugin[reference documentation of the {publishplugin}] +:keywords: publish, publishing, plugin Publishing a plugin is the primary way to make it available for others to use. While you can publish to a private repository to restrict access, publishing to the https://plugins.gradle.org[{portal}] makes your plugin available to anyone in the world. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/reporting_problems.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/reporting_problems.adoc index 6a448b7d0f411..d56901a09f79b 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/reporting_problems.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/plugins/reporting_problems.adoc @@ -14,6 +14,7 @@ [[sec:reporting_problems]] = Reporting problems +:keywords: problems, api, problem Plugins can report problems through Gradle's problems-reporting APIs. The APIs report rich, structured information about problems happening during the build. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/composite_builds.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/composite_builds.adoc index 8ad383620ef8e..1666188ff0254 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/composite_builds.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/composite_builds.adoc @@ -14,33 +14,35 @@ [[composite_builds]] = Composite Builds +:keywords: composite, include, included, build A composite build is a build that includes other builds. -image::structuring-builds-4.png[] - [[composite_build_intro]] A composite build is similar to a Gradle multi-project build, except that instead of including `subprojects`, entire `builds` are included. +[[defining_composite_builds]] +== Composite Build Layout + Composite builds allow you to: * Combine builds that are usually developed independently, for instance, when trying out a bug fix in a library that your application uses. * Decompose a large multi-project build into smaller, more isolated chunks that can be worked on independently or together as needed. A build that is included in a composite build is referred to as an *included build*. + +image::structuring-builds-4.png[] + Included builds do not share any configuration with the composite build or the other included builds. Each included build is configured and executed in isolation. -[[defining_composite_builds]] -== Defining a composite build - -The following example demonstrates how two Gradle builds, normally developed separately, can be combined into a composite build. +The following example demonstrates how two Gradle builds, normally developed separately, can be combined into a composite build: -[source,text] +[.multi-language-sample] +===== +[source, kotlin] ---- my-composite -├── gradle -├── gradlew ├── settings.gradle.kts ├── build.gradle.kts ├── my-app @@ -57,6 +59,30 @@ my-composite ├── build.gradle.kts └── src/main/java/org/sample/stringutils/Strings.java ---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +my-composite +├── settings.gradle +├── build.gradle +├── my-app +│ ├── settings.gradle +│ └── app +│ ├── build.gradle +│ └── src/main/java/org/sample/my-app/Main.java +└── my-utils + ├── settings.gradle + ├── number-utils + │ ├── build.gradle + │ └── src/main/java/org/sample/numberutils/Numbers.java + └── string-utils + ├── build.gradle + └── src/main/java/org/sample/stringutils/Strings.java + +---- +===== The `my-utils` multi-project build produces two Java libraries, `number-utils` and `string-utils`. The `my-app` build produces an executable using functions from those libraries. @@ -64,13 +90,21 @@ The `my-app` build produces an executable using functions from those libraries. The `my-app` build does not depend directly on `my-utils`. Instead, it declares binary dependencies on the libraries produced by `my-utils`: +++++ +

+ +

+ +

+++++ + ==== include::sample[dir="samples/build-organization/composite-builds/basic/kotlin",files="my-app/app/build.gradle.kts[tags=app_dependencies]"] include::sample[dir="samples/build-organization/composite-builds/basic/groovy",files="my-app/app/build.gradle[tags=app_dependencies]"] ==== [[command_line_composite]] -=== Defining a composite build via `--include-build` +== Defining a Composite Build via `--include-build` The `--include-build` command-line argument turns the executed build into a composite, substituting dependencies from the included build into the executed build. @@ -82,7 +116,7 @@ include::{samplesPath}/build-organization/composite-builds/basic/tests/basicCli. ---- [[settings_defined_composite]] -=== Defining a composite build via the settings file +== Defining a Composite Build via the Settings file It's possible to make the above arrangement persistent by using link:{groovyDslPath}/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeBuild(java.lang.Object)[Settings.includeBuild(java.lang.Object)] to declare the included build in the `settings.gradle(.kts)` file. @@ -90,15 +124,22 @@ The settings file can be used to add subprojects and included builds simultaneou Included builds are added by location: -.settings.gradle.kts -[source,kotlin] ----- -includeBuild("my-utils") ----- +==== +include::sample[dir="samples/build-organization/composite-builds/basic/kotlin",files="settings.gradle.kts[tags=inc]"] +include::sample[dir="samples/build-organization/composite-builds/basic/groovy",files="settings.gradle[tags=inc]"] +==== [[separate_composite]] In the example, the settings.gradle(.kts) file combines otherwise separate builds: +++++ +

+ +

+++++ + ==== include::sample[dir="samples/build-organization/composite-builds/basic/kotlin",files="settings.gradle.kts[]"] include::sample[dir="samples/build-organization/composite-builds/basic/groovy",files="settings.gradle[]"] @@ -114,7 +155,7 @@ include::sample[dir="samples/build-organization/composite-builds/basic/groovy",f ==== [[included_plugin_builds]] -=== Including builds that define Gradle plugins +=== Including Builds that define Gradle Plugins A special case of included builds are builds that define Gradle plugins. @@ -122,13 +163,21 @@ These builds should be included using the `includeBuild` statement inside the `p Using this mechanism, the included build may also contribute a settings plugin that can be applied in the settings file itself: +++++ +

+ +

+++++ + ==== include::sample[dir="snippets/developingPlugins/testingPlugins/kotlin/include-plugin-build",files="settings.gradle.kts[tags=include-build]"] include::sample[dir="snippets/developingPlugins/testingPlugins/groovy/include-plugin-build",files="settings.gradle[tags=include-build]"] ==== [[included_builds]] -== Restrictions on included builds +== Restrictions on Included Builds Most builds can be included in a composite, including other composite builds. There are some restrictions. @@ -168,7 +217,7 @@ In other words, the nested composite build structure is flattened. ==== [[interacting_with_composite_builds]] -== Interacting with a composite build +== Interacting with a Composite Build Interacting with a composite build is generally similar to a regular multi-project build. Tasks can be executed, tests can be run, and builds can be imported into the IDE. @@ -204,7 +253,7 @@ For every included build, each subproject is included as an IntelliJ IDEA Module Source dependencies are configured, providing cross-build navigation and refactoring. [[included_build_declaring_substitutions]] -== Declaring dependencies substituted by an included build +== Declaring dependencies substituted by an Included Build By default, Gradle will configure each included build to determine the dependencies it can provide. The algorithm for doing this is simple. @@ -222,6 +271,14 @@ For these cases, explicitly declaring the substitutions for an included build is For example, a single-project build called `anonymous-library`, produces a Java utility library but does not declare a value for the group attribute: +++++ +

+ +

+++++ + ==== include::sample[dir="samples/build-organization/composite-builds/declared-substitution/kotlin/anonymous-library",files="build.gradle.kts[]"] include::sample[dir="samples/build-organization/composite-builds/declared-substitution/groovy/anonymous-library",files="build.gradle[]"] @@ -248,6 +305,14 @@ This is necessary because the rules are globally applied in the build, and Gradl For example, we create a separate `publishedRuntimeClasspath` configuration that gets resolved to the published versions of modules that also exist in one of the local builds. This is done by deactivating global dependency substitution rules: +++++ +

+ +

+++++ + ==== include::sample[dir="snippets/dependencyManagement/customizingResolution-deactivateGlobalSubstitution/kotlin",files="build.gradle.kts[tags=disableGlobalDependencySubstitutionRules]"] include::sample[dir="snippets/dependencyManagement/customizingResolution-deactivateGlobalSubstitution/groovy",files="build.gradle[tags=disableGlobalDependencySubstitutionRules]"] @@ -282,13 +347,21 @@ Here are some cases where the published module metadata may be different from th Builds using these features function incorrectly when included in a composite build. [[included_build_task_dependencies]] -== Depending on tasks in an included build +== Depending on Tasks in an Included Build While included builds are isolated from one another and cannot declare direct dependencies, a composite build can declare task dependencies on its included builds. The included builds are accessed using link:{groovyDslPath}/org.gradle.api.invocation.Gradle.html#org.gradle.api.invocation.Gradle:includedBuilds[Gradle.getIncludedBuilds()] or link:{groovyDslPath}/org.gradle.api.invocation.Gradle.html#org.gradle.api.invocation.Gradle:includedBuild(java.lang.String)[Gradle.includedBuild(java.lang.String)], and a task reference is obtained via the link:{groovyDslPath}/org.gradle.api.initialization.IncludedBuild.html#org.gradle.api.initialization.IncludedBuild:task(java.lang.String)[IncludedBuild.task(java.lang.String)] method. Using these APIs, it is possible to declare a dependency on a task in a particular included build: +++++ +

+ +

+++++ + ==== include::sample[dir="samples/build-organization/composite-builds/basic/kotlin",files="build.gradle.kts[tags=run]"] include::sample[dir="samples/build-organization/composite-builds/basic/groovy",files="build.gradle[tags=run]"] @@ -296,13 +369,21 @@ include::sample[dir="samples/build-organization/composite-builds/basic/groovy",f Or you can declare a dependency on tasks with a certain path in some or all of the included builds: +++++ +

+ +

+++++ + ==== include::sample[dir="samples/build-organization/composite-builds/hierarchical-multirepo/kotlin",files="build.gradle.kts"] include::sample[dir="samples/build-organization/composite-builds/hierarchical-multirepo/groovy",files="build.gradle"] ==== [[current_limitations_and_future_work]] -== Limitations of composite builds +== Limitations of Composite Builds Limitations of the current implementation include: diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/declaring_dependencies_between_subprojects.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/declaring_dependencies_between_subprojects.adoc deleted file mode 100644 index c7db0a97f4a34..0000000000000 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/declaring_dependencies_between_subprojects.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Copyright (C) 2024 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. - -[[declaring_dependencies_between_subprojects]] -= Declaring Dependencies between Subprojects - -What if one subproject depends on another subproject? -What if one project needs the artifact produced by another project? - -image::structuring-builds-2.png[] - -This is a common use case for multi-project builds. -Gradle offers <> for this. - -[[sec:project_jar_dependencies]] -== Depending on another project - -Let's explore a theoretical multi-project build with the following layout: - -[.multi-language-sample] -===== -[source, kotlin] ----- -. -├── api -│ ├── src -│ │ └──... -│ └── build.gradle.kts -├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle.kts -├── shared -│ ├── src -│ │ └──... -│ └── build.gradle.kts -└── settings.gradle.kts ----- -===== -[.multi-language-sample] -===== -[source, groovy] ----- -. -├── api -│ ├── src -│ │ └──... -│ └── build.gradle -├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle -├── shared -│ ├── src -│ │ └──... -│ └── build.gradle -└── settings.gradle ----- -===== - -In this example, there are three subprojects called `shared`, `api`, and `person-service`: - -1. The `person-service` subproject depends on the other two subprojects, `shared` and `api`. -2. The `api` subproject depends on the `shared` subproject. - -We use the `:` separator to define a <> such as `services:person-service` or `:shared`. -Consult the DSL documentation of link:{groovyDslPath}++/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String[])++[Settings.include(java.lang.String[\])] for more information about defining project paths. - -[[javadependencies_2]] -==== -include::sample[dir="snippets/multiproject/basic-dependencies/kotlin",files="settings.gradle.kts[];shared/build.gradle.kts[];api/build.gradle.kts[];services/person-service/build.gradle.kts[]"] -include::sample[dir="snippets/multiproject/basic-dependencies/groovy",files="settings.gradle[];shared/build.gradle[];api/build.gradle[];services/person-service/build.gradle[]"] -==== - -A project dependency affects execution order. -It causes the other project to be built first and adds the output with the classes of the other project to the classpath. -It also adds the dependencies of the other project to the classpath. - -If you execute `./gradlew :api:compile`, first the `shared` project is built, and then the `api` project is built. - -[[sec:depending_on_output_of_another_project]] -== Depending on artifacts produced by another project - -Sometimes, you might want to depend on the output of a specific task within another project rather than the entire project. -However, explicitly declaring a task dependency from one project to another is discouraged as it introduces unnecessary coupling between tasks. - -The recommended way to model dependencies, where a task in one project depends on the output of another, is to produce the output and mark it as an "outgoing" artifact. -Gradle's <> allows you to share arbitrary artifacts between projects and build them on demand. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_builds.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_builds.adoc index 2790f9c7d31ea..fdb9ec4edf44b 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_builds.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_builds.adoc @@ -13,157 +13,87 @@ // limitations under the License. [[multi_project_builds]] -= Structuring Projects with Gradle += Multi-Project Builds +:keywords: multi, build, project -It is important to structure your Gradle project to optimize build performance. -A multi-project build is the standard in Gradle. +As projects grow, it's common to split them into smaller, focused modules that are built, tested, and released together. +Gradle supports this through multi-project builds, allowing you to organize related codebases under a single build while keeping each module logically isolated. -image::structuring-builds-1.png[] +== Multi-Project Layout -A multi-project build consists of one root project and one or more subprojects. -Gradle can build the root project and any number of the subprojects in a single execution. +A multi-project build consists of a root project and one or more subprojects, all defined in a single `settings.gradle(.kts)` file. +This structure supports modularization, parallel execution, and code reuse. -[[sub:project_locations]] -== Project locations +image::structuring-builds-6.png[] -Multi-project builds contain a single root project in a directory that Gradle views as the root path: `.`. - -Subprojects are located physically under the root path: `./subproject`. - -A subproject has <>, which denotes the position of that subproject in the multi-project build. -In most cases, the project path is consistent with its location in the file system. - -The project structure is created in the `settings.gradle(.kts)` file. -The settings file must be present in the root directory. - -[[sec:creating_multi_project_builds]] -== A simple multi-project build - -Let's look at a _basic_ multi-project build example that contains a root project and a single subproject. - -The root project is called `basic-multiproject`, located somewhere on your machine. -From Gradle's perspective, the root is the top-level directory `.`. - -The project contains a single subproject called `./app`: +A typical multi-project structure looks like this: [.multi-language-sample] ===== [source, kotlin] ---- -. -├── app -│ ... -│ └── build.gradle.kts -└── settings.gradle.kts +my-project/ +├── settings.gradle.kts // <1> +├── build.gradle.kts // <2> +├── app/ // <3> +│ └── build.gradle.kts // <4> +├── core/ // <3> +│ └── build.gradle.kts // <5> +└── util/ // <3> + └── build.gradle.kts // <6> ---- ===== [.multi-language-sample] ===== [source, groovy] ---- -. -├── app -│ ... -│ └── build.gradle -└── settings.gradle +my-project/ +├── settings.gradle // <1> +├── build.gradle // <2> +├── app/ // <3> +│ └── build.gradle // <4> +├── core/ // <3> +│ └── build.gradle // <5> +└── util/ // <3> + └── build.gradle // <6> ---- ===== +<1> Declares subprojects +<2> Root project build logic (optional) +<3> Subproject +<4> App module +<5> Shared core logic +<6> Utility code -This is the recommended project structure for starting any Gradle project. -The <> also generates skeleton projects that follow this structure - a root project with a single subproject: - -The `settings.gradle(.kts)` file describes the project structure to Gradle: - -==== -include::sample[dir="snippets/multiproject/basic-multiproject/kotlin",files="settings.gradle.kts[]"] -include::sample[dir="snippets/multiproject/basic-multiproject/groovy",files="settings.gradle[]"] -==== - -In this case, Gradle will look for a build file for the `app` subproject in the `./app` directory. - -You can view the structure of a multi-project build by running the `projects` command: - ----- -$ ./gradlew -q projects -include::{snippetsPath}/multiproject/basic-multiproject/tests/projects.out[] ----- - -In this example, the `app` subproject is a Java application that applies the <> and configures the main class. -The application prints `Hello World` to the console: - -==== -include::sample[dir="snippets/multiproject/basic-multiproject/kotlin",files="app/build.gradle.kts[]"] -include::sample[dir="snippets/multiproject/basic-multiproject/groovy",files="app/build.gradle[]"] -.app/src/main/java/com/example/Hello.java -[source, java] ----- -include::{snippetsPath}/multiproject/basic-multiproject/groovy/app/src/main/java/com/example/Hello.java[] ----- -==== - -You can run the application by executing the `run` task from the <> in the project root: ----- -$ ./gradlew -q run -include::{snippetsPath}/multiproject/basic-multiproject/tests/run.out[] ----- - -[[sub:building_the_tree]] -== Adding a subproject - -In the settings file, you can use the `include` method to add another subproject to the root project: - -==== -include::sample[dir="snippets/multiproject/standardLayouts/kotlin",files="settings.gradle.kts[tags=hierarchical-layout]"] -include::sample[dir="snippets/multiproject/standardLayouts/groovy",files="settings.gradle[tags=hierarchical-layout]"] -==== - -The `include` method takes <> as arguments. -The project path is assumed to be equal to the relative physical file system path. -For example, a path `services:api` is mapped by default to a folder `./services/api` (relative to the project root `.`). - -More examples of how to work with the project path can be found in the DSL documentation of link:{groovyDslPath}++/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String[])++[Settings.include(java.lang.String[\])]. +Each subproject can define its own build logic, dependencies, and plugins. -Let's add another subproject called `lib` to the previously created project. - -All we need to do is add another `include` statement in the root settings file: -==== -include::sample[dir="snippets/multiproject/multiple-subprojects/kotlin",files="settings.gradle.kts[]"] -include::sample[dir="snippets/multiproject/multiple-subprojects/groovy",files="settings.gradle[]"] -==== - -Gradle will then look for the build file of the new `lib` subproject in the `./lib/` directory: +In `settings.gradle(.kts)`, you include subprojects by name using `include()`. +The `include()` method takes <> as arguments: [.multi-language-sample] ===== [source, kotlin] ---- -. -├── app -│ ... -│ └── build.gradle.kts -├── lib -│ ... -│ └── build.gradle.kts -└── settings.gradle.kts +rootProject.name = "my-project" +include("app", "core", "util") ---- ===== [.multi-language-sample] ===== [source, groovy] ---- -. -├── app -│ ... -│ └── build.gradle -├── lib -│ ... -│ └── build.gradle -└── settings.gradle +rootProject.name = 'my-project' +include('app', 'core', 'util') ---- ===== +By default, a project path corresponds to the relative physical location of the project directory. +For example, the path `services:api` maps to the directory `./services/api`, relative to the root project. + +You can find more examples and detailed usage in the DSL reference for link:{groovyDslPath}++/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String[])++[`Settings.include(String...)`]. + [[sub:modifying_element_of_the_project_tree]] -== Project Descriptors +=== Project Descriptors To further describe the project architecture to Gradle, the settings file provides _project descriptors_. @@ -171,6 +101,14 @@ You can modify these descriptors in the settings file at any time. To access a descriptor, you can: +++++ +

+ +

+++++ + ==== include::sample[dir="snippets/multiproject/customLayout/kotlin",files="settings.gradle.kts[tags=lookup-project]"] include::sample[dir="snippets/multiproject/customLayout/groovy",files="settings.gradle[tags=lookup-project]"] @@ -194,15 +132,14 @@ Let's take a hypothetical project with the following structure: [source, kotlin] ---- . -├── app -│ ... -│ └── build.gradle.kts -├── subs // Gradle may see this as a subproject -│ └── web // Gradle may see this as a subproject -│ └── my-web-module // Intended subproject -│ ... -│ └── build.gradle.kts -└── settings.gradle.kts +├── settings.gradle.kts +├── app/ +│ ├── build.gradle.kts +│ └── src/ +└── subs/ // <1> + ├── build.gradle.kts + └── web // <1> + └── my-web-module // <2> ---- ===== [.multi-language-sample] @@ -210,33 +147,41 @@ Let's take a hypothetical project with the following structure: [source, groovy] ---- . -├── app -│ ... -│ └── build.gradle -├── subs // Gradle may see this as a subproject -│ └── web // Gradle may see this as a subproject -│ └── my-web-module // Intended subproject -│ ... -│ └── build.gradle -└── settings.gradle +├── settings.gradle +├── app/ +│ ├── build.gradle +│ └── src/ +└── subs/ // <1> + ├── build.gradle + └── web // <1> + └── my-web-module // <2> + ---- ===== +<1> Gradle may see this as a subproject +<2> Actual intended subproject If your `settings.gradle(.kts)` looks like this: -``` +[source,groovy] +---- include(':subs:web:my-web-module') -``` +---- + +Gradle sees a subproject with a logical project name of `:subs:web:my-web-module` and two, possibly unintentional, other subprojects logically named: + +1. `:subs` +2. `:subs:web` -Gradle sees a subproject with a logical project name of `:subs:web:my-web-module` and two, possibly unintentional, other subprojects logically named `:subs` and `:subs:web`. This can lead to phantom build directories, especially when using `allprojects{}` or `subproject{}`. To avoid this, you can use: -``` +[source,kotlin] +---- include(':my-web-module') project(':my-web-module').projectDir = "subs/web/my-web-module" -``` +---- So that you only end up with a single subproject named `:my-web-module`. @@ -246,6 +191,7 @@ So, while the physical project layout is the same, the logical results are diffe == Naming recommendations As your project grows, naming and consistency get increasingly more important. + To keep your builds maintainable, we recommend the following: 1. *Keep default project names for subprojects*: @@ -259,3 +205,106 @@ All letters are lowercase, and words are separated with a dash (`-`) character. The `rootProject.name` effectively assigns a name to the build, used in reports like Build Scans. If the root project name is not set, the name will be the container directory name, which can be unstable (i.e., you can check out your project in any directory). The name will be generated randomly if the root project name is not set and checked out to a file system's root (e.g., `/` or `C:\`). + +[[declaring_dependencies_between_subprojects]] +== Declaring dependencies between Subprojects + +What if one subproject depends on another? +What if one subproject depends on the artifact produced by another? + +image::structuring-builds-7.png[] + +This is a common use case in multi-project builds. +Gradle supports this scenario with <>. + +[[sec:project_jar_dependencies]] +=== Depending on another Project + +Consider a multi-project build with the following layout: + +[.multi-language-sample] +===== +[source, kotlin] +---- +. +├── api +│ ├── src +│ │ └──... +│ └── build.gradle.kts +├── services +│ └── person-service +│ ├── src +│ │ └──... +│ └── build.gradle.kts +├── shared +│ ├── src +│ │ └──... +│ └── build.gradle.kts +└── settings.gradle.kts +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. +├── api +│ ├── src +│ │ └──... +│ └── build.gradle +├── services +│ └── person-service +│ ├── src +│ │ └──... +│ └── build.gradle +├── shared +│ ├── src +│ │ └──... +│ └── build.gradle +└── settings.gradle +---- +===== + +In this example: + +1. `person-service` depends on both `api` and `shared` +2. `api` depends on `shared` + +You declare these relationships using the project path, which uses colons (`:`) to indicate nesting. +For example: + +- `:shared` refers to the `shared` subproject +- `services:person-service` refers to a nested subproject + +++++ +

+ +

+++++ + +[[javadependencies_2]] +==== +include::sample[dir="snippets/multiproject/basic-dependencies/kotlin",files="settings.gradle.kts[];shared/build.gradle.kts[];api/build.gradle.kts[];services/person-service/build.gradle.kts[]"] +include::sample[dir="snippets/multiproject/basic-dependencies/groovy",files="settings.gradle[];shared/build.gradle[];api/build.gradle[];services/person-service/build.gradle[]"] +==== + +For more details on project paths, consult the DSL documentation for link:{groovyDslPath}++/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String[])++[Settings.include(String...)]. + +A project dependency affects both the build order and classpath: + +- The required project will be built first. +- Its compiled classes and transitive dependencies are added to the consuming project’s classpath. + +For example, running `./gradlew :api:compileJava` will first build `shared`, then `api`. + +[[sec:depending_on_output_of_another_project]] +=== Depending on Artifacts produced by another Project + +Sometimes, you only need the output of a specific task from another project—not the entire project itself. + +While you can create task-to-task dependencies between projects, Gradle discourages this because it creates tight coupling between tasks. + +Instead, use outgoing artifacts to expose a task’s output and model it as a dependency. +Gradle’s <> allows one project to consume artifacts from another in a structured, on-demand way. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_configuration_and_execution.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_configuration_and_execution.adoc index d3a521e271fd1..e1879cff925b5 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_configuration_and_execution.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/multi_project_configuration_and_execution.adoc @@ -46,7 +46,7 @@ To configure on demand for a given build, see <> and <<#configuration_and_execution,configuration on demand>>. +While this flexibility empowers build authors, it limits Gradle's ability to perform optimizations such as <<#sec:parallel_execution,parallel project builds>> and <<#configuration_and_execution,configuration on demand>>. Projects are considered decoupled when they interact solely through declared dependencies and task dependencies. Any direct modification or reading of another project's object creates coupling between the projects. @@ -61,7 +61,7 @@ To avoid coupling issues, it's recommended to: As Gradle evolves, it aims to provide features that leverage decoupled projects while offering solutions for common use cases like configuration injection without introducing coupling. -[[sec:mp_parallel_execution]] +[[sec:parallel_execution]] == Parallel projects Gradle's parallel execution feature optimizes CPU utilization to accelerate builds by concurrently executing tasks from different projects. diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/organizing_gradle_projects.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/organizing_gradle_projects.adoc new file mode 100644 index 0000000000000..3500dec36ad9c --- /dev/null +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/organizing_gradle_projects.adoc @@ -0,0 +1,562 @@ +// Copyright (C) 2024 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. + +[[organizing_gradle_projects]] += Structuring and Organizing Gradle Projects + +It is important to structure your Gradle project to optimize build performance. +A multi-project build is the standard in Gradle. + +[[sub:project_locations]] +== Project Concepts + +There are four key concepts to understand Gradle projects: + +1. **Root project**: The top-level project in a build that contains the `settings.gradle(.kts)` file and typically aggregates all subprojects. + +2. **Subprojects**: Individual modules (components) that are part of a multi-project build and are included by the root project via the `settings.gradle(.kts)` file. + +3. **Settings file**: A `settings.gradle(.kts)` configuration file used to define the structure of a multi-project build, including which subprojects are part of it and optionally how they're named or located. + +4. **Build scripts**: `build.gradle(.kts)` files that define how a project is built (applying plugins, declaring dependencies, configuring tasks, etc...) executed per project (subprojects can each have one). + +Let's take a look at an example: + +[.multi-language-sample] +===== +[source, kotlin] +---- +my-project/ // <1> +├── settings.gradle.kts // <2> +├── app/ // <3> +│ ├── build.gradle.kts // <4> +│ └── src/ +├── core/ // <3> +│ ├── build.gradle.kts // <4> +│ └── src/ +└── util/ // <3> + ├── build.gradle.kts // <4> + └── src/ +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +my-project/ // <1> +├── settings.gradle // <2> +├── app/ // <3> +│ ├── build.gradle // <4> +│ └── src/ +├── core/ // <3> +│ ├── build.gradle // <4> +│ └── src/ +└── util/ // <3> + ├── build.gradle // <4> + └── src/ +---- +===== +<1> Root project directory +<2> Settings file +<3> Subproject +<4> Subproject build file + +[[sec:creating_single_project_builds]] +== Single-Project Build + +image::structuring-builds-1.png[] + +Let's look at a _basic_ multi-project build example that contains a root project and a single subproject. + +The root project is called `my-project`, located somewhere on your machine. +From Gradle's perspective, the root is the top-level directory `.`. + +The project contains a single subproject called `app`: + +[.multi-language-sample] +===== +[source, kotlin] +---- +. // <1> +├── settings.gradle // <2> +└── app/ // <3> + ├── build.gradle // <4> + └── src/ // <5> +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. // <1> +├── settings.gradle.kts // <2> +└── app/ // <3> + ├── build.gradle.kts // <4> + └── src/ // <5> +---- +===== +<1> Root project +<2> Subproject +<3> Subproject build file +<4> Settings file +<5> Source code and more + +This is the recommended project structure for starting any Gradle project. +The <> also generates skeleton projects that follow this structure - a root project with a single subproject: + +The `settings.gradle(.kts)` file describes the project structure to Gradle: + +++++ +

+ +

+++++ + +==== +include::sample[dir="snippets/multiproject/basic-multiproject/kotlin",files="settings.gradle.kts[]"] +include::sample[dir="snippets/multiproject/basic-multiproject/groovy",files="settings.gradle[]"] +==== + +In this case, Gradle will look for a build file for the `app` subproject in the `./app` directory. + +You can view the structure of a multi-project build by running the `projects` command: + +---- +$ ./gradlew -q projects +include::{snippetsPath}/multiproject/basic-multiproject/tests/projects.out[] +---- + +In this example, the `app` subproject is a Java application that applies the <> and configures the main class. + +The application prints `Hello World` to the console: + +==== +include::sample[dir="snippets/multiproject/basic-multiproject/kotlin",files="app/build.gradle.kts[]"] +include::sample[dir="snippets/multiproject/basic-multiproject/groovy",files="app/build.gradle[]"] +.app/src/main/java/com/example/Hello.java +[source, java] +---- +include::{snippetsPath}/multiproject/basic-multiproject/groovy/app/src/main/java/com/example/Hello.java[] +---- +==== + +You can run the application by executing the `run` task from the <> in the project root: +---- +$ ./gradlew -q run +include::{snippetsPath}/multiproject/basic-multiproject/tests/run.out[] +---- + +[[sec:creating_multi_project_builds]] +== Multi-Project Build (`include()`) + +image::structuring-builds-2.png[] + +In the settings file, you can use the `include` method to add another subproject to the root project: + +++++ +

+ +

+++++ + +==== +include::sample[dir="snippets/multiproject/standardLayouts/kotlin",files="settings.gradle.kts[tags=hierarchical-layout]"] +include::sample[dir="snippets/multiproject/standardLayouts/groovy",files="settings.gradle[tags=hierarchical-layout]"] +==== + +The `include` method takes <> as arguments. +The project path is assumed to be equal to the relative physical file system path. +For example, a path `services:api` is mapped by default to a folder `./services/api` (relative to the project root `.`). + +More examples of how to work with the project path can be found in the DSL documentation of link:{groovyDslPath}++/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String[])++[Settings.include(java.lang.String[\])]. + +Let's add another subproject called `lib` to the previously created project. + +All we need to do is add another `include` statement in the root settings file: + +++++ +

+ +

+++++ + +==== +include::sample[dir="snippets/multiproject/multiple-subprojects/kotlin",files="settings.gradle.kts[]"] +include::sample[dir="snippets/multiproject/multiple-subprojects/groovy",files="settings.gradle[]"] +==== + +Gradle will then look for the build file of the new `lib` subproject in the `./lib/` directory: + +[.multi-language-sample] +===== +[source, kotlin] +---- +. // <1> +├── settings.gradle.kts // <2> +├── app/ // <3> +│ ├── build.gradle.kts // <4> +│ └── src/ +└── lib/ // <3> + ├── build.gradle.kts // <4> + └── src/ +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. // <1> +├── settings.gradle // <2> +├── app/ // <3> +│ ├── build.gradle // <4> +│ └── src/ +└── lib/ // <3> + ├── build.gradle // <4> + └── src/ +---- +===== +<1> Root project +<2> Settings file +<3> Subproject +<4> Subproject build file + +You can learn more about multi-project builds in <>. + +[[sec:build_sources]] +== Sharing Build Logic (`buildSrc`) + +image::structuring-builds-3.png[] + +When projects grow in size and complexity, it's common to see the same logic repeated across multiple subprojects—like applying the same plugins, configuring the same tasks, or declaring the same dependencies. + +Duplicated build logic is hard to maintain and easy to get wrong. +Gradle provides a built-in way to centralize and reuse this logic: a special directory called `buildSrc`. + +`buildSrc` is a separate build located in the root of your Gradle project. +Any code you put in this directory is automatically compiled and added to the classpath of your main build. + +Let's take a look at our multi-project build: + +[.multi-language-sample] +===== +[source, kotlin] +---- +. +├── settings.gradle.kts +├── app/ +│ ├── build.gradle.kts // <1> +│ └── src/ +└── lib/ + ├── build.gradle.kts // <1> + └── src/ +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. +├── settings.gradle +├── app/ +│ ├── build.gradle // <1> +│ └── src/ +└── lib/ + ├── build.gradle // <1> + └── src/ +---- +===== +<1> Subproject build script, applies `java-library` and testing logic + +We now encapsulate reusable configuration logic in a `java-library-convention.gradle.kts` file. + +Because the file is named `java-library-convention.gradle.kts`, Gradle automatically registers it as a plugin with the ID `java-library-convention`. +It compiles and makes this plugin available to all other build scripts in the project. + +[.multi-language-sample] +===== +[source, kotlin] +---- +. +├── settings.gradle.kts +├── buildSrc/ +│ ├── build.gradle.kts +│ └── src/main/kotin/ +│ └── java-library-convention.gradle.kts // <1> +├── app/ +│ ├── build.gradle.kts // <2> +│ └── src/ +└── lib/ + ├── build.gradle.kts // <2> + └── src/ +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. +├── settings.gradle +├── buildSrc/ +│ ├── build.gradle +│ └── src/main/groovy/ +│ └── java-library-convention.gradle // <1> +├── app/ +│ ├── build.gradle // <2> +│ └── src/ +└── lib/ + ├── build.gradle // <2> + └── src/ +---- +===== +<1> Applies `java-library` and testing logic +<2> Subproject build script, applies `java-library` and testing logic + +You can learn more about multi-project builds in <>. + +[[sec:composite_builds]] +== Composite Builds (`includeBuild()`) + +image::structuring-builds-4.png[] + +In Gradle, composite builds (or included builds) are ways to compose multiple builds together. + +They allow you to work with multiple Gradle projects (builds) as if they were part of a single build, without needing to publish artifacts to a repository. + +Imagine we want to break up our multi-project build into two separate builds: + +- A shared library in `libs` +- An application that uses it (our previous multi-project build) + +We want to: + +- Keep them in separate builds (they could be in separate repos) +- But develop them together without publishing `lib` + +[.multi-language-sample] +===== +[source, kotlin] +---- +. +├── settings.gradle.kts +├── buildSrc/ +│ ├── build.gradle.kts +│ └── src/main/kotin/ +│ └── java-library-convention.gradle.kts +├── app/ +│ ├── build.gradle.kts +│ └── src/ +├── core/ +│ ├── build.gradle.kts +│ └── src/ +├── util/ +│ ├── build.gradle.kts +│ └── src/ +└── libs/ // <1> + └── lib/ + ├── settings.gradle.kts + ├── build.gradle.kts + └── src/ +---- +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. +├── settings.gradle +├── buildSrc/ +│ ├── build.gradle +│ └── src/main/groovy/ +│ └── java-library-convention.gradle +├── app/ +│ ├── build.gradle +│ └── src/ +├── core/ +│ ├── build.gradle +│ └── src/ +├── util/ +│ ├── build.gradle +│ └── src/ +└── libs/ // <1> + └── lib/ + ├── settings.gradle + ├── build.gradle + └── src/ +---- +===== +<1> Standalone, reusable library (included build) + +Here, `lib` is a separate Gradle build that lives in `libs/lib`. +It’s not part of the normal `include(...)` multi-project structure. + +Instead, we treat it as an included build, a distinct build that we can use without publishing it to a repository. + +In the root `settings.gradle(.kts)`, we tell Gradle to include `lib` as part of a composite build using `includeBuild()`: + +++++ +

+ +

+++++ + +==== +include::sample[dir="snippets/dependencyManagement/customizingResolution-capabilitySubstitutionRule/kotlin",files="settings.gradle.kts[tags=inc]"] +include::sample[dir="snippets/dependencyManagement/customizingResolution-capabilitySubstitutionRule/groovy",files="settings.gradle[tags=inc]"] +==== + +You can learn more about multi-project builds in <>. + +[[sec:structuring_recommendations]] +== Structuring Recommendations + +Source code and build logic should be organized in a clear, consistent, and meaningful way. +This section outlines recommendations that lead to readable and maintainable Gradle projects. +It also highlights common pitfalls and how to avoid them to ensure your builds stay robust and scalable. + +[[sec:separate_language_source_files]] +=== Use separate Language-specific Source Files + +Gradle's language plugins define conventions for discovering and compiling source code. +For example, when the <> is applied, Gradle automatically compiles source files in `src/main/java`. + +Other language plugins follow a similar convention: the last part of the source directory (e.g., `java`, `groovy`, `kotlin`) indicates the language of the source files it contains. + +Some compilers support cross-compilation of multiple languages from the same directory. +For example, the Groovy compiler can compile both Java and Groovy source files from `src/main/groovy`. + +However, Gradle recommends separating source files by language into distinct directories (e.g., `src/main/java` and `src/main/kotlin`). +This improves build performance and makes builds more predictable—both for Gradle and for humans reading the project layout. + +Here’s an example source layout for a project using both Java and Kotlin: + +==== +[.multi-language-sample] +===== +[source,kotlin] +---- +. +├── build.gradle.kts +└── src + └── main + ├── java + │ └── HelloWorld.java + └── kotlin + └── Utils.kt +---- +===== +[.multi-language-sample] +===== +[source,groovy] +---- +. +├── build.gradle +└── src + └── main + ├── java + │ └── HelloWorld.java + └── kotlin + └── Utils.kt +---- +===== +==== + +[[sec:separate_test_type_source_files]] +=== Use separate Source Files per Test type + +It's common for a project to define and run multiple types of tests—such as unit tests, integration tests, functional tests, or smoke tests. +To keep things maintainable and organized, Gradle recommends storing each test type’s source code in its own dedicated source directory. + +For example, instead of placing all tests under `src/test/java`, you might use: + +[source,text] +---- +src/ +├── test/ // Unit tests +│ └── java/ +├── integrationTest/ // Integration tests +│ └── java/ +└── functionalTest/ // Functional tests + └── java/ +---- + +To see how this works in practice, check out the +link:../samples/sample_jvm_multi_project_with_additional_test_types.html[example project] which demonstrates how to define a custom `integrationTest` source set and task in a Java-based project. + +NOTE: Gradle allows you to define multiple source sets and test tasks, so you can fully isolate and control each type of test in your build. + +[[sec:use_standard_conventions]] +=== Use standard Conventions + +All Gradle core plugins follow the *convention over configuration* principle, a well-known software engineering paradigm that favors sensible defaults over manual setup. +You can read more about it here: link:https://en.wikipedia.org/wiki/Convention_over_configuration[Convention over configuration]. + +Gradle plugins provide predefined behaviors and directory structures that "just work" in most cases. +Let’s take the <> as an example: + +* The default source directory is `src/main/java`. +* The default output location for compiled classes and packaged artifacts (like JARs) is `build/`. + +While Gradle allows you to override most defaults, doing so can make your build harder to understand and maintain—especially for teams or newcomers. + +TIP: Stick to standard conventions unless you have a strong reason to deviate (e.g., adapting to a legacy layout). +Refer to the reference documentation for each plugin to learn about its default conventions and behaviors. + +[[sec:settings_file]] +=== Use a Settings file + +Every time you run a Gradle build, Gradle attempts to locate a `settings.gradle` (Groovy DSL) or `settings.gradle.kts` (Kotlin DSL) file. +To do this, it walks up the directory hierarchy from the current working directory to the filesystem root. +As soon as it finds a settings file, it stops searching and uses that as the entry point for the build. + +In a <>, the settings file is *required*. +It defines which projects are part of the build and enables Gradle to correctly configure and evaluate the entire project hierarchy. + +You may also need a settings file to <> to the build classpath using `pluginManagement` or `dependencyResolutionManagement`. + +The following example shows a standard Gradle project layout: + +==== +[.multi-language-sample] +===== +[source,kotlin] +---- +. +├── settings.gradle.kts +├── subproject-one +│ └── build.gradle.kts +└── subproject-two + └── build.gradle.kts +---- +===== +[.multi-language-sample] +===== +[source,groovy] +---- +. +├── settings.gradle +├── subproject-one +│ └── build.gradle +└── subproject-two + └── build.gradle +---- +===== +==== diff --git a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/sharing_build_logic_between_subprojects.adoc b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/sharing_build_logic_between_subprojects.adoc index a32999ff77db4..78e016019b37d 100644 --- a/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/sharing_build_logic_between_subprojects.adoc +++ b/platforms/documentation/docs/src/docs/userguide/authoring-builds/structuring/sharing_build_logic_between_subprojects.adoc @@ -12,354 +12,274 @@ // See the License for the specific language governing permissions and // limitations under the License. - [[sharing_build_logic_between_subprojects]] -= Sharing Build Logic between Subprojects -:keywords: buildsrc,build-logic - -Subprojects in a multi-project build typically share some common dependencies. - -image::structuring-builds-3.png[] - -Instead of copying and pasting the same Java version and libraries in each subproject build script, Gradle provides a special directory for storing shared build logic that can be automatically applied to subprojects. - -[[sec:using_buildsrc]] -== Share logic in `buildSrc` - -`buildSrc` is a Gradle-recognized and protected directory which comes with some benefits: - -1. *Reusable Build Logic*: -+ -`buildSrc` allows you to organize and centralize your custom build logic, tasks, and plugins in a structured manner. -The code written in buildSrc can be reused across your project, making it easier to maintain and share common build functionality. += Sharing Build Logic using `buildSrc` +:keywords: buildsrc, build-logic, allprojects, subprojects -2. *Isolation from the Main Build*: -+ -Code placed in `buildSrc` is isolated from the other build scripts of your project. -This helps keep the main build scripts cleaner and more focused on project-specific configurations. +Subprojects in a multi-project build often share common dependencies. -3. *Automatic Compilation and Classpath*: -+ -The contents of the `buildSrc` directory are automatically compiled and included in the classpath of your main build. -This means that classes and plugins defined in buildSrc can be directly used in your project's build scripts without any additional configuration. +Rather than duplicating the same dependency declarations across multiple build scripts, Gradle allows you to centralize shared build logic in a special directory. +This way, you can declare the dependency version in one place and have it automatically apply to all subprojects. -4. *Ease of Testing*: -+ -Since `buildSrc` is a separate build, it allows for easy testing of your custom build logic. -You can write tests for your build code, ensuring that it behaves as expected. +image::structuring-builds-8.png[] -5. *Gradle Plugin Development*: -+ -If you are developing custom Gradle plugins for your project, `buildSrc` is a convenient place to house the plugin code. -This makes the plugins easily accessible within your project. - -The `buildSrc` directory is treated as an <>. +[[sec:sharing_logic_via_convention_plugins]] +== Using `buildSrc` -For multi-project builds, there can be only one `buildSrc` directory, which must be in the root project directory. +`buildSrc` is a special directory in a Gradle build that allows you to organize and share build logic, such as custom plugins, tasks, configurations, and utility functions, across all projects in your build. -NOTE: The downside of using `buildSrc` is that any change to it will invalidate every task in your project and require a rerun. +image::structuring-builds-9.png[] -`buildSrc` uses the same <> applicable to Java, Groovy, and Kotlin projects. -It also provides direct access to the Gradle API. +Let's take a look at an example with the following structure: -A typical project including `buildSrc` has the following layout: +A typical multi-project build has the following layout: [.multi-language-sample] ===== [source, kotlin] ---- . -├── buildSrc -│ ├── src -│ │ └──main -│ │ └──kotlin -│ │ └──MyCustomTask.kt // <1> -│ ├── shared.gradle.kts // <2> -│ └── build.gradle.kts ├── api -│ ├── src -│ │ └──... -│ └── build.gradle.kts // <3> +│ ├── src/ +│ └── build.gradle.kts // <1> ├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle.kts // <3> +│ ├── src/ +│ └── build.gradle.kts // <1> ├── shared -│ ├── src -│ │ └──... -│ └── build.gradle.kts +│ ├── src/ +│ └── build.gradle.kts // <1> └── settings.gradle.kts ---- -<1> Create the `MyCustomTask` task. -<2> A shared build script. -<3> Uses the `MyCustomTask` task and shared build script. +<1> A build script that contains build logic, including parts that are shared with other subprojects. ===== [.multi-language-sample] ===== [source, groovy] ---- . -├── buildSrc -│ ├── src -│ │ └──main -│ │ └──groovy -│ │ └──MyCustomTask.groovy // <1> -│ ├── shared.gradle // <2> -│ └── build.gradle ├── api -│ ├── src -│ │ └──... -│ └── build.gradle // <3> +│ ├── src/ +│ └── build.gradle // <1> ├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle // <3> +│ ├── src/ +│ └── build.gradle // <1> ├── shared -│ ├── src -│ │ └──... -│ └── build.gradle +│ ├── src/ +│ └── build.gradle // <1> └── settings.gradle ---- -<1> Create the `MyCustomTask` task. -<2> A shared build script. -<3> Uses the `MyCustomTask` task and shared build script. +<1> A build script that contains build logic, including parts that are shared with other subprojects. ===== -In the `buildSrc`, the build script `shared.gradle(.kts)` is created. -It contains dependencies and other build information that is common to multiple subprojects: +The build file for `api`, `services`, and `shared` has many commonalities: -[.multi-language-sample] -===== -.shared.gradle.kts -[source, kotlin] ----- -repositories { - mavenCentral() -} +++++ +

+ +

+++++ -dependencies { - implementation("org.slf4j:slf4j-api:1.7.32") -} ----- -===== -[.multi-language-sample] -===== -.shared.gradle -[source, groovy] ----- -repositories { - mavenCentral() -} - -dependencies { - implementation 'org.slf4j:slf4j-api:1.7.32' -} ----- -===== - -In the `buildSrc`, the `MyCustomTask` is also created. -It is a helper task that is used as part of the build logic for multiple subprojects: +==== +include::sample[dir="snippets/multiproject/no-buildSrc/kotlin",files="api/build.gradle.kts[tags=common-logic];services/build.gradle.kts[tags=common-logic];shared/build.gradle.kts[tags=common-logic]"] +include::sample[dir="snippets/multiproject/no-buildSrc/groovy",files="api/build.gradle[tags=common-logic];services/build.gradle[tags=common-logic];shared/build.gradle[tags=common-logic]"] +==== -[.multi-language-sample] -===== -.MyCustomTask.kt -[source, kotlin] ----- -import org.gradle.api.DefaultTask -import org.gradle.api.tasks.TaskAction - -open class MyCustomTask : DefaultTask() { - @TaskAction - fun calculateSum() { - // Custom logic to calculate the sum of two numbers - val num1 = 5 - val num2 = 7 - val sum = num1 + num2 - - // Print the result - println("Sum: $sum") - } -} ----- -===== -[.multi-language-sample] -===== -.MyCustomTask.groovy -[source, groovy] ----- -import org.gradle.api.DefaultTask -import org.gradle.api.tasks.TaskAction - -class MyCustomTask extends DefaultTask { - @TaskAction - void calculateSum() { - // Custom logic to calculate the sum of two numbers - int num1 = 5 - int num2 = 7 - int sum = num1 + num2 - - // Print the result - println "Sum: $sum" - } -} ----- -===== +To avoid duplicating build logic across `api`, `services`, and `shared`, we can move the shared parts into `buildSrc`. +This allows us to define dependencies and other configurations once and apply them uniformly to all subprojects. -The `MyCustomTask` task is used in the build script of the `api` and `shared` projects. -The task is automatically available because it's part of `buildSrc`. +For example, if you need to update the version of `org.slf4j:slf4j-api:1.7.32`, you only have to change it once—in the build logic inside `buildSrc`—rather than updating every individual build script. -The `shared.gradle(.kts)` file is also applied: +Let's expand the layout to include a `buildSrc` directory: [.multi-language-sample] ===== -.build.gradle.kts [source, kotlin] ---- -// Apply any other configurations specific to your project - -// Use the build script defined in buildSrc -apply(from = rootProject.file("buildSrc/shared.gradle.kts")) - -// Use the custom task defined in buildSrc -tasks.register("myCustomTask") ----- -===== -[.multi-language-sample] -===== -.build.gradle -[source, groovy] ----- -// Apply any other configurations specific to your project - -// Use the build script defined in buildSrc -apply from: rootProject.file('buildSrc/shared.gradle') - -// Use the custom task defined in buildSrc -tasks.register('myCustomTask', MyCustomTask) ----- -===== - -[[sec:sharing_logic_via_convention_plugins]] -== Share logic using convention plugins - -Gradle's recommended way of organizing build logic is to use its plugin system. - -We can write a plugin that encapsulates the build logic common to several subprojects in a project. -This kind of plugin is called a *convention plugin*. - -While writing plugins is outside the scope of this section, the recommended way to build a Gradle project is to put common build logic in a convention plugin located in the `buildSrc`. - -Let's take a look at an example project: - -==== -[.multi-language-sample] -===== -[source,kotlin] ----- . ├── buildSrc │ ├── src │ │ └──main │ │ └──kotlin -│ │ └──myproject.java-conventions.gradle.kts // <1> +│ │ └──java-common-conventions.gradle.kts // <1> │ └── build.gradle.kts ├── api -│ ├── src -│ │ └──... -│ └── build.gradle.kts // <2> +│ ├── src/ +│ └── build.gradle.kts // <2> ├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle.kts // <2> +│ ├── src/ +│ └── build.gradle.kts // <2> ├── shared -│ ├── src -│ │ └──... -│ └── build.gradle.kts // <2> +│ ├── src/ +│ └── build.gradle.kts // <2> └── settings.gradle.kts ---- -<1> Create the `myproject.java-conventions` convention plugin. -<2> Applies the `myproject.java-conventions` convention plugin. +<1> A shared build script. +<2> Applies the shared build script. ===== [.multi-language-sample] ===== -[source,groovy] +[source, groovy] ---- . ├── buildSrc │ ├── src │ │ └──main │ │ └──groovy -│ │ └──myproject.java-conventions.gradle // <1> +│ │ └──java-common-conventions.gradle // <1> │ └── build.gradle ├── api -│ ├── src -│ │ └──... -│ └── build.gradle // <2> +│ ├── src/ +│ └── build.gradle // <2> ├── services -│ └── person-service -│ ├── src -│ │ └──... -│ └── build.gradle // <2> +│ ├── src/ +│ └── build.gradle // <2> ├── shared -│ ├── src -│ │ └──... -│ └── build.gradle // <2> +│ ├── src/ +│ └── build.gradle // <2> └── settings.gradle ---- -<1> Create the `myproject.java-conventions` convention plugin. -<2> Applies the `myproject.java-conventions` convention plugin. +<1> A shared build script. +<2> Applies the shared build script. ===== -==== -This build contains three subprojects: +When a `buildSrc` directory is present at the root of a Gradle build, Gradle treats it as a <>. +Upon detecting the `buildSrc` directory, Gradle: -==== -include::sample[dir="snippets/multiproject/dependencies-java/kotlin",files="settings.gradle.kts[]"] -include::sample[dir="snippets/multiproject/dependencies-java/groovy",files="settings.gradle[]"] -==== +- Treats `buildSrc` as an independent Gradle project with its own `build.gradle(.kts)` file and its own `src/` folder. +- Compiles all classes and scripts in `buildSrc` (typically under `src/main/kotlin` or `src/main/groovy`) before evaluating any other build scripts in the main build. +- Makes the compiled classes and scripts available on the classpath of all other project build scripts in the root project and subprojects. -The source code for the convention plugin created in the `buildSrc` directory is as follows: +As such, our new `buildSrc` has the following build file: ==== -include::sample[dir="snippets/multiproject/dependencies-java/kotlin",files="buildSrc/src/main/kotlin/myproject.java-conventions.gradle.kts[]"] -include::sample[dir="snippets/multiproject/dependencies-java/groovy",files="buildSrc/src/main/groovy/myproject.java-conventions.gradle[]"] +include::sample[dir="snippets/multiproject/buildSrc/kotlin",files="buildSrc/build.gradle.kts[]"] +include::sample[dir="snippets/multiproject/buildSrc/groovy",files="buildSrc/build.gradle[]"] ==== -For the convention plugin to compile, basic configuration needs to be applied in the build file of the `buildSrc` directory: +In the `buildSrc`, the build script `java-common-conventions.gradle(.kts)` is created in `src/main/kotlin` or `src/main/groovy`. +It contains dependencies and other build information that is common to our subprojects: ==== -include::sample[dir="snippets/multiproject/dependencies-java/kotlin",files="buildSrc/build.gradle.kts[]"] -include::sample[dir="snippets/multiproject/dependencies-java/groovy",files="buildSrc/build.gradle[]"] +include::sample[dir="snippets/multiproject/buildSrc/kotlin",files="buildSrc/src/main/kotlin/java-common-conventions.gradle.kts[]"] +include::sample[dir="snippets/multiproject/buildSrc/groovy",files="buildSrc/src/main/groovy/java-common-conventions.gradle[]"] ==== -The convention plugin is applied to the `api`, `shared`, and `person-service` subprojects: +If you create a script file like `java-common-conventions.gradle(.kts)`, you can treat it as a plugin and apply it in your subprojects. +The ID of the plugin is the name of the build file without the `gradle(.kts)` extension. +This kind of plugin is called a *convention plugin*. + +The shared logic is removed from the `api`, `services`, and `shared` build files. +And the `shared` plugin is applied in the files instead: + +++++ +

+ +

+++++ ==== -include::sample[dir="snippets/multiproject/dependencies-java/kotlin",files="api/build.gradle.kts[];shared/build.gradle.kts[];services/person-service/build.gradle.kts[]"] -include::sample[dir="snippets/multiproject/dependencies-java/groovy",files="api/build.gradle[];shared/build.gradle[];services/person-service/build.gradle[]"] +include::sample[dir="snippets/multiproject/buildSrc/kotlin",files="api/build.gradle.kts[tags=non-common-logic];services/build.gradle.kts[tags=non-common-logic];shared/build.gradle.kts[tags=non-common-logic]"] +include::sample[dir="snippets/multiproject/buildSrc/groovy",files="api/build.gradle[tags=non-common-logic];services/build.gradle[tags=non-common-logic];shared/build.gradle[tags=non-common-logic]"] ==== +From now on, if you want to change something like the version of `slf4j-api`, you only need to update it in `buildSrc`, and the change will automatically apply to all subprojects. + +[[sec:using_buildsrc]] +== About the `buildSrc` directory + +`buildSrc` is a special, Gradle-recognized directory that provides a convenient way to organize and reuse custom build logic across your build. Gradle automatically treats it as an included build with several advantages: + +1. **Reusable Build Logic**: You can centralize common build logic, tasks, and plugins in `buildSrc`. This promotes consistency and maintainability across subprojects, as changes in `buildSrc` are automatically reflected wherever its logic is used. + +2. **Automatic Compilation and Classpath Inclusion**: Gradle automatically compiles the code in `buildSrc` and includes it in the classpath of all build scripts. This allows classes, plugins, and utilities defined in `buildSrc` to be used directly without additional setup. + +3. **Cleaner Build Scripts**: Moving logic into `buildSrc` keeps your project’s main build scripts focused and decluttered, improving readability and maintainability. + +4. **Ease of Testing**: Since `buildSrc` is treated as a standalone build, you can write and run unit tests for your custom tasks and plugins just like any other project code. + +5. **Convenient Plugin Development**: If you're writing custom Gradle plugins for internal use, `buildSrc` provides an easy way to define and use them without publishing to an external repository. + +`buildSrc` follows the same <> as regular Java, Groovy, or Kotlin projects and has direct access to the Gradle API. +Dependencies can be declared in its own `build.gradle` or `build.gradle.kts` file. + +In a multi-project build, only one `buildSrc` directory is allowed, and it must reside in the root project directory. + +WARNING: Changes to code in `buildSrc` will invalidate the configuration phase and require re-execution of all tasks, potentially slowing down the build. + +=== Using a Composite Build Named `build-logic` + +In addition to `buildSrc`, another powerful way to share build logic across subprojects is by using a dedicated composite build, typically named `build-logic`. + +A typical multi-project build using `build-logic` as a composite build looks like this: + +[.multi-language-sample] +===== +[source, kotlin] +---- +. +├── build-logic/ // <1> +│ ├── build.gradle.kts +│ ├── settings.gradle.kts +│ └── src/main/kotlin +│ └── java-common-conventions.gradle.kts +├── api/ +│ └── build.gradle.kts // <2> +├── services/ +│ └── build.gradle.kts // <2> +├── shared/ +│ └── build.gradle.kts // <2> +└── settings.gradle.kts // <3> +---- +<1> Standalone build logic project that defines convention plugins. +<2> Applies shared plugin(s) from the composite build. +<3> Includes build-logic as an included build. +===== +[.multi-language-sample] +===== +[source, groovy] +---- +. +├── build-logic/ // <1> +│ ├── build.gradle +│ ├── settings.gradle +│ └── src/main/groovy +│ └── java-common-conventions.gradle +├── api/ +│ └── build.gradle // <2> +├── services/ +│ └── build.gradle // <2> +├── shared/ +│ └── build.gradle // <2> +└── settings.gradle // <3> +---- +<1> Standalone build logic project that defines convention plugins. +<2> Applies shared plugin(s) from the composite build. +<3> Includes `build-logic` as an included build. +===== + +You can learn more in <>. + [[sec:convention_plugins_vs_cross_configuration]] -== Do not use cross-project configuration +== Avoid cross-project configuration using `subprojects` and `allprojects` An improper way to share build logic between subprojects is _cross-project configuration_ via the link:{javadocPath}/org/gradle/api/Project.html#subprojects-groovy.lang.Closure-[`subprojects {}`] and link:{javadocPath}/org/gradle/api/Project.html#allprojects-groovy.lang.Closure-[`allprojects {}`] DSL constructs. -TIP: Avoid using `subprojects {}` and `allprojects {}`. - With <>, build logic can be injected into a subproject which is not obvious when looking at its build script. In the long run, cross-project configuration usually grows in complexity and becomes a burden. Cross-project configuration can also introduce configuration-time coupling between projects, which can prevent optimizations like configuration-on-demand from working properly. -=== Convention plugins versus cross-project configuration +== Convention plugins versus cross-project configuration The two most common uses of cross-project configuration can be better modeled using convention plugins: 1. Applying plugins or other configurations to subprojects of a certain type. + Often, the cross-project configuration logic is `if subproject is of type X, then configure Y`. This is equivalent to applying `X-conventions` plugin directly to a subproject. + 2. Extracting information from subprojects of a certain type. + This use case can be modeled using <>. diff --git a/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices.adoc b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices.adoc index baf76c27f9c44..3367d4b6253f4 100644 --- a/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices.adoc +++ b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices.adoc @@ -44,10 +44,15 @@ The items in this guide are meant to be _brief_, _understandable_, and _actionab == Best Practices -- <> -- <> -- <> +- <> +- <> +- <> -== Further Reference +== Other Advice + +- <> +- <> + +== References - <> diff --git a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_dependencies.adoc b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_dependencies.adoc similarity index 89% rename from platforms/documentation/docs/src/docs/userguide/best-practices/bp_dependencies.adoc rename to platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_dependencies.adoc index c3bb79fb4f364..d69689ddede76 100644 --- a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_dependencies.adoc +++ b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_dependencies.adoc @@ -38,12 +38,8 @@ To influence resolved versions, check out <> Avoid declaring versions in `project.ext`, constants, or local variables: ==== -include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin",files="gradle/libs.versions.toml[]"] -==== - -==== -include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin/do-this",files="build.gradle.kts[tags=do-this]"] -include::sample[dir="snippets/bestPractices/useVersionCatalogs/groovy/do-this",files="build.gradle[tags=do-this]"] +include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin/avoid-this",files="build.gradle.kts[tags=avoid-this]"] +include::sample[dir="snippets/bestPractices/useVersionCatalogs/groovy/avoid-this",files="build.gradle[tags=avoid-this]"] ==== Avoid misusing version catalogs for unrelated concerns: @@ -56,8 +52,12 @@ Avoid misusing version catalogs for unrelated concerns: Use a centralized `libs.versions.toml` file in your `gradle/` directory: ==== -include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin/avoid-this",files="build.gradle.kts[tags=avoid-this]"] -include::sample[dir="snippets/bestPractices/useVersionCatalogs/groovy/avoid-this",files="build.gradle[tags=avoid-this]"] +include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin",files="gradle/libs.versions.toml[]"] +==== + +==== +include::sample[dir="snippets/bestPractices/useVersionCatalogs/kotlin/do-this",files="build.gradle.kts[tags=do-this]"] +include::sample[dir="snippets/bestPractices/useVersionCatalogs/groovy/do-this",files="build.gradle[tags=do-this]"] ==== === References @@ -104,7 +104,7 @@ The following guidelines help in naming catalog entries effectively: + *Example*: For `org.owasp:dependency-check-gradle`, use `dependency-check-plugin` -=== Examples +=== Example ==== include::sample[dir="snippets/bestPractices/versionCatalogNaming/kotlin",files="gradle/libs.versions.toml[]"] @@ -124,7 +124,7 @@ include::sample[dir="snippets/bestPractices/versionCatalogNaming/groovy",files=" `<>` [[set_up_repositories_in_settings]] -== Set up your dependency repositories in `settings.gradle.kts` +== Set up your Dependency Repositories in the Settings file Declare your repositories for your plugins and dependencies in `settings.gradle.kts`. @@ -132,11 +132,11 @@ Declare your repositories for your plugins and dependencies in `settings.gradle. Using `settings.gradle.kts` file to declare repositories has several benefits: - - Avoids repetition: Centralizing repository declarations eliminates the need to repeat them in each project's `build.gradle.kts`. - - Improves debuggability: Ensures all projects resolve dependencies during resolution from the same repositories, in a consistent order. - - Matches the build model: Repositories are not part of the project definition; they are part of global build logic, so settings is a more appropriate place for them. + - *Avoids repetition*: Centralizing repository declarations eliminates the need to repeat them in each project's `build.gradle.kts`. + - *Improves debuggability*: Ensures all projects resolve dependencies during resolution from the same repositories, in a consistent order. + - *Matches the build model*: Repositories are not part of the project definition; they are part of global build logic, so settings is a more appropriate place for them. -Note: While https://github.com/gradle/gradle/issues/32443[`dependencyResolutionManagement.repositories` is an incubating API], it is the preferred way of declaring repositories. +NOTE: While https://github.com/gradle/gradle/issues/32443[`dependencyResolutionManagement.repositories` is an incubating API], it is the preferred way of declaring repositories. === Example @@ -164,7 +164,6 @@ include::sample[dir="snippets/bestPractices/settingsRepositoriesDo/groovy",files [[dont_depend_on_kotlin_stdlib]] == Don't Explicitly Depend on the Kotlin Standard Library -:keywords: dependencies The Kotlin Gradle Plugin automatically adds a dependency on the Kotlin standard library (`stdlib`) to each source set, so there is no need to declare it explicitly. @@ -193,7 +192,7 @@ include::sample[dir="snippets/bestPractices/kotlinStdLib-do/kotlin",files="build include::sample[dir="snippets/bestPractices/kotlinStdLib-do/groovy",files="build.gradle[tags=do-this]"] ==== -*`stdlib` dependency is not included explicitly*: The standard library remains available for use, and source code requiring it can be compiled without any issues. +<1> *`stdlib` dependency is not included explicitly*: The standard library remains available for use, and source code requiring it can be compiled without any issues. === References @@ -212,8 +211,8 @@ Avoid declaring the same dependency multiple times, especially when it is alread Duplicating dependencies in Gradle build scripts can lead to: -* Increased maintenance: Declaring a dependency in multiple places makes it harder to manage. -* Unexpected behavior: Declaring the same dependency in multiple configurations (e.g., `compileOnly` and `implementation`) can result in hard-to-diagnose classpath issues. +* *Increased maintenance*: Declaring a dependency in multiple places makes it harder to manage. +* *Unexpected behavior*: Declaring the same dependency in multiple configurations (e.g., `compileOnly` and `implementation`) can result in hard-to-diagnose classpath issues. === Example @@ -236,4 +235,5 @@ include::sample[dir="snippets/bestPractices/avoidDuplicateDependencies/groovy/do <1> Declare dependency once === Tags -`<>` \ No newline at end of file + +`<>` diff --git a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_general.adoc b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_general.adoc similarity index 93% rename from platforms/documentation/docs/src/docs/userguide/best-practices/bp_general.adoc rename to platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_general.adoc index e59f4ebaceb73..61887164e5d42 100644 --- a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_general.adoc +++ b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_general.adoc @@ -24,9 +24,9 @@ Prefer the Kotlin DSL (`build.gradle.kts`) over the Groovy DSL (`build.gradle`) The Kotlin DSL offers several advantages over the Groovy DSL: -* Strict typing: IDEs provide better auto-completion and navigation with the Kotlin DSL. -* Improved readability: Code written in Kotlin is often easier to follow and understand. -* Single-language stack: Projects that already use Kotlin for production and test code don’t need to introduce Groovy just for the build. +* *Strict typing*: IDEs provide better auto-completion and navigation with the Kotlin DSL. +* *Improved readability*: Code written in Kotlin is often easier to follow and understand. +* *Single-language stack*: Projects that already use Kotlin for production and test code don’t need to introduce Groovy just for the build. Since Gradle 8.0, link:https://blog.gradle.org/kotlin-dsl-is-now-the-default-for-new-gradle-builds[Kotlin DSL is the default] for new builds created with `gradle init`. Android Studio also link:https://developer.android.com/build/migrate-to-kotlin-dsl#timeline[defaults to Kotlin DSL]. @@ -77,8 +77,6 @@ Always use the latest compatible version of each plugin: * Test plugin compatibility using link:https://slack.engineering/shadow-jobs/[shadow jobs]. * Consult changelogs when updating. -=== Stay Informed - Subscribe to the Gradle link:https://newsletter.gradle.org/[newsletter] to stay informed about new Gradle releases, features, and plugins. === References @@ -87,11 +85,10 @@ Subscribe to the Gradle link:https://newsletter.gradle.org/[newsletter] to stay === Tags -`#plugins` +<> [[use_the_plugins_block]] == Apply Plugins Using the `plugins` Block -:keywords: plugins,structuring-builds You should always use the `plugins` block to <> in your build scripts. @@ -129,7 +126,7 @@ include::sample[dir="snippets/bestPractices/usePluginsBlock-do/groovy",files="bu === References -<> +- <> === Tags @@ -137,7 +134,6 @@ include::sample[dir="snippets/bestPractices/usePluginsBlock-do/groovy",files="bu [[do_not_use_internal_apis]] == Do Not Use Internal APIs -:keywords: upgrades Do not use APIs from a package where any segment of the package is `internal`, or types that have `Internal` or `Impl` as a suffix in the name. @@ -176,4 +172,4 @@ include::sample[dir="snippets/bestPractices/avoidInternal/groovy",files="build.g === Tags -`<>` \ No newline at end of file +<> diff --git a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_tasks.adoc b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_tasks.adoc similarity index 95% rename from platforms/documentation/docs/src/docs/userguide/best-practices/bp_tasks.adoc rename to platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_tasks.adoc index 625cdb28ddff0..7d460483e632f 100644 --- a/platforms/documentation/docs/src/docs/userguide/best-practices/bp_tasks.adoc +++ b/platforms/documentation/docs/src/docs/userguide/best-practices/best_practices_tasks.adoc @@ -17,7 +17,6 @@ [[avoid_depends_on]] == Avoid DependsOn -:keywords: tasks,inputs-and-outputs,up-to-date-checking The task link:{javadocPath}/org/gradle/api/DefaultTask.html#setDependsOn(java.lang.Iterable)[dependsOn] method should only be used for <> (tasks without task actions). @@ -38,8 +37,8 @@ include::sample[dir="snippets/bestPractices/avoidDependsOn/kotlin",files="build. include::sample[dir="snippets/bestPractices/avoidDependsOn/groovy",files="build.gradle[tags=depended-upon-task-setup]"] ==== -<1> *Task With Multiple Outputs*: `hellowWorld` task prints "Hello" to its `messageFile` and "World" to its `audienceFile`. -<2> *Registering the Task*: `hellowWorld` produces "message.txt" and "audience.txt" outputs. +<1> *Task With Multiple Outputs*: `helloWorld` task prints "Hello" to its `messageFile` and "World" to its `audienceFile`. +<2> *Registering the Task*: `helloWorld` produces "message.txt" and "audience.txt" outputs. ==== Don't Do This @@ -63,6 +62,7 @@ include::sample[dir="snippets/bestPractices/avoidDependsOn/groovy",files="build. ==== <1> *Register Implicit Task Dependency*: `translateGood` requires only one of the files that is produced by `helloWorld`. + Gradle now understands that `translateGood` requires `helloWorld` to have run successfully first because it needs to create the `message.txt` file which is then used by the translation task. Gradle can use this information to optimize task scheduling. Using the `map` method avoids eagerly retrieving the `helloWorld` task until the output is needed to determine if `translateGood` should run. @@ -76,8 +76,7 @@ Using the `map` method avoids eagerly retrieving the `helloWorld` task until the `<>`, `<>`, `<>` [[use_cacheability_annotations]] -== Favor `@CacheableTask` and `@DisableCachingByDefault` Over `cacheIf(Spec)` and `doNotCacheIf(String, Spec)` -:keywords: tasks,caching +== Favor `@CacheableTask` and `@DisableCachingByDefault` over `cacheIf(Spec)` and `doNotCacheIf(String, Spec)` The link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#cacheIf(org.gradle.api.specs.Spec)[`cacheIf`] and link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#doNotCacheIf(java.lang.String,org.gradle.api.specs.Spec)[`doNotCacheIf`] methods should only be used in situations where the <> of a task varies between different task instances or cannot be determined until the task is executed by Gradle. You should instead favor annotating the task class itself with link:{javadocPath}/org/gradle/api/tasks/CacheableTask.html[`@CacheableTask`] annotation for any task that is _always_ cacheable. diff --git a/platforms/documentation/docs/src/docs/userguide/dep-man/centralizing-dependencies/version_catalogs.adoc b/platforms/documentation/docs/src/docs/userguide/dep-man/centralizing-dependencies/version_catalogs.adoc index 056a2f4a4b58b..48ca7134e8f71 100644 --- a/platforms/documentation/docs/src/docs/userguide/dep-man/centralizing-dependencies/version_catalogs.adoc +++ b/platforms/documentation/docs/src/docs/userguide/dep-man/centralizing-dependencies/version_catalogs.adoc @@ -14,6 +14,7 @@ [[version-catalog]] = Version Catalogs +:keywords: toml, libs.versions.toml A version catalog is a selected list of dependencies that can be referenced in build scripts, simplifying dependency management. diff --git a/platforms/documentation/docs/src/docs/userguide/dep-man/controlling-dependency-resolution/artifact_transforms.adoc b/platforms/documentation/docs/src/docs/userguide/dep-man/controlling-dependency-resolution/artifact_transforms.adoc index ee1316fb71c08..752d42911d509 100644 --- a/platforms/documentation/docs/src/docs/userguide/dep-man/controlling-dependency-resolution/artifact_transforms.adoc +++ b/platforms/documentation/docs/src/docs/userguide/dep-man/controlling-dependency-resolution/artifact_transforms.adoc @@ -29,7 +29,9 @@ This is done as the last step when resolving artifacts, before tasks or tools li Each component exposes a set of <>, where each variant is identified by a set of <> (i.e., key-value pairs such as `debug=true`). When Gradle resolves a configuration, it looks at each dependency, resolves it to a component, and selects the corresponding variant from that component that matches the requested attributes. -If the component does not have a matching variant, resolution fails *unless* Gradle can construct a sequence of transformations that will modify an existing artifact to create a valid match (without changing its transitive dependencies). +The variant contains one or more artifacts, which represent the concrete outputs produced by a component (such as JAR files, resources, or native binaries). +However, a consumer may need artifacts in a format that doesn't directly match any available variant. +Rather than requiring producers to explicitly publish every possible variant, Gradle provides a powerful mechanism to dynamically adapt artifacts to the required form. **Artifact Transforms** are a mechanism for converting one type of artifact into another during the build process. They provide the consumer an efficient and flexible mechanism for transforming the artifacts of a given producer to the required format without needing the producer to expose variants in that format. diff --git a/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-dependencies/declaring_configurations.adoc b/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-dependencies/declaring_configurations.adoc index 7c51d0a6eaae0..2b0ffdc47fb37 100644 --- a/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-dependencies/declaring_configurations.adoc +++ b/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-dependencies/declaring_configurations.adoc @@ -14,6 +14,7 @@ [[declaring-dependency-configurations]] = Declaring Dependency Configurations +:keywords: configuration [[sec:what-are-dependency-configurations]] In Gradle, dependencies are associated with specific scopes, such as compile-time or runtime. diff --git a/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-repositories/centralizing_repositories.adoc b/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-repositories/centralizing_repositories.adoc index 8e7bf690637bb..93ec3048eeae8 100644 --- a/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-repositories/centralizing_repositories.adoc +++ b/platforms/documentation/docs/src/docs/userguide/dep-man/declaring-repositories/centralizing_repositories.adoc @@ -39,7 +39,7 @@ include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=prefer_projects]"] ==== -[[sec:available-modes] +[[sec:available-modes]] == Available modes There are three modes for dependency resolution management: diff --git a/platforms/documentation/docs/src/docs/userguide/dep-man/publishing/publishing_gradle_module_metadata.adoc b/platforms/documentation/docs/src/docs/userguide/dep-man/publishing/publishing_gradle_module_metadata.adoc index 9e2ad3e9657cf..0a4fb912720cf 100644 --- a/platforms/documentation/docs/src/docs/userguide/dep-man/publishing/publishing_gradle_module_metadata.adoc +++ b/platforms/documentation/docs/src/docs/userguide/dep-man/publishing/publishing_gradle_module_metadata.adoc @@ -15,7 +15,7 @@ :metadata-file-spec: https://github.com/gradle/gradle/blob/master/platforms/documentation/docs/src/docs/design/gradle-module-metadata-latest-specification.md [[sec:understanding-gradle-module-md]] -= Understanding Gradle Module Metadata += Gradle Module Metadata Gradle Module Metadata is a format used to serialize the Gradle component model. It is similar to https://maven.apache.org/pom.html[Apache Maven™'s POM file] or https://ant.apache.org/ivy/[Apache Ivy™ ivy.xml] files. diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-1.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-1.png index 04af7d92d28f5..a710e2aec405a 100644 Binary files a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-1.png and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-1.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-2.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-2.png index 10cd22b6c5608..efdac5dca8c56 100644 Binary files a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-2.png and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-2.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-3.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-3.png index d5428bbcf997c..de623c4b9c1c5 100644 Binary files a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-3.png and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-3.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-4.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-4.png index 20035439d57d3..d21144c873e6a 100644 Binary files a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-4.png and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-4.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-6.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-6.png new file mode 100644 index 0000000000000..36c52d0c80ae5 Binary files /dev/null and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-6.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-7.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-7.png new file mode 100644 index 0000000000000..78c5f7fd62c47 Binary files /dev/null and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-7.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-8.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-8.png new file mode 100644 index 0000000000000..290ad5e589849 Binary files /dev/null and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-8.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-9.png b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-9.png new file mode 100644 index 0000000000000..e20d1a4b667e4 Binary files /dev/null and b/platforms/documentation/docs/src/docs/userguide/img/structuring-builds-9.png differ diff --git a/platforms/documentation/docs/src/docs/userguide/integration/tooling_api.adoc b/platforms/documentation/docs/src/docs/userguide/integration/tooling_api.adoc index a1f2f434c93d8..4eee4b6b2376e 100644 --- a/platforms/documentation/docs/src/docs/userguide/integration/tooling_api.adoc +++ b/platforms/documentation/docs/src/docs/userguide/integration/tooling_api.adoc @@ -14,6 +14,7 @@ [[tooling_api]] = Tooling API +:keywords: tapi [[embedding]] == Embedding Gradle using the Tooling API diff --git a/platforms/documentation/docs/src/docs/userguide/licenses.adoc b/platforms/documentation/docs/src/docs/userguide/licenses.adoc index 3f129b98c9c3a..884fad6c6e37e 100644 --- a/platforms/documentation/docs/src/docs/userguide/licenses.adoc +++ b/platforms/documentation/docs/src/docs/userguide/licenses.adoc @@ -18,8 +18,7 @@ [[sec:gradle_documentation]] == Gradle Documentation -Copyright © 2024 Gradle, Inc. All rights reserved. -Gradle is a trademark of Gradle, Inc. +© 2025 Gradle, Inc. Gradle®, Develocity®, Build Scan®, and the Gradlephant logo are registered trademarks of Gradle, Inc. On this resource, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle, Inc. and/or its subsidiaries. Gradle's Build Tool source code is open-source and licensed under the link:https://github.com/gradle/gradle/blob/master/LICENSE[Apache License 2.0]. diff --git a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/additional/incremental_build.adoc b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/additional/incremental_build.adoc index 43d0ad484e75b..8e2b61c8219da 100644 --- a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/additional/incremental_build.adoc +++ b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/additional/incremental_build.adoc @@ -14,6 +14,7 @@ [[incremental_build]] = Incremental build +:keywords: Classpath, InputFiles, InputDirectory, InputFile, Input, CompileClasspath, OutputFile, OutputDirectory, OutputFiles, OutputDirectories, Destroys, LocalState, Nested, Console, Internal, ReplacedBy, SkipWhenEmpty, Incremental, Optional, PathSensitive, IgnoreEmptyDirectories, NormalizeLineEndings An important part of any build tool is the ability to avoid doing work that has already been done. Consider the process of compilation. @@ -361,7 +362,7 @@ Specifically, they never can be: * up-to-date, * loaded from or stored in the <>, -* executed in parallel with other tasks, even if <> is enabled, +* executed in parallel with other tasks, even if <> is enabled, * executed incrementally. The in-memory representation of the file system state (_<>)_ is also invalidated before an invalid task is executed. diff --git a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/configuration_cache.adoc b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/configuration_cache.adoc index da01d0a52b39c..92f8573ff4df2 100644 --- a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/configuration_cache.adoc +++ b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/configuration_cache.adoc @@ -16,6 +16,7 @@ [[config_cache]] = Configuration Cache +:keywords: configuration-cache, no-configuration-cache, org.gradle.configuration-cache, org.gradle.configuration-cache.problems, org.gradle.configuration-cache.max-problems, org.gradle.configuration-cache.parallel, STABLE_CONFIGURATION_CACHE, // Run tests for snippets included in this chapter with: // ./gradlew :docs:docsTest --tests="ExemplarExternalSamplesFunctionalTest.snippet-configuration-cache-*" diff --git a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/performance.adoc b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/performance.adoc index ce584414beae3..c06fb3af1060a 100644 --- a/platforms/documentation/docs/src/docs/userguide/optimizing-builds/performance.adoc +++ b/platforms/documentation/docs/src/docs/userguide/optimizing-builds/performance.adoc @@ -31,7 +31,7 @@ This section explores ways to optimize performance, highlights common pitfalls, |<> |2 -|<> +|<> |3 |<> @@ -132,7 +132,7 @@ plugins { } ---- -[[sec:parallel_execution]] +[[sec:enable_parallel_execution]] == 2. Enable Parallel Execution Most projects consist of multiple subprojects, some of which are independent. @@ -873,7 +873,7 @@ include::sample[dir="snippets/performance/parallelTestExecution/groovy",files="b ==== Gradle reuses the forked process for the duration of the build, so the startup cost is low. -Running compilation in its own JVM helps reduce garbage collection in the main Gradle process, which can speed up the rest of your build — especially when used alongside <>. +Running compilation in its own JVM helps reduce garbage collection in the main Gradle process, which can speed up the rest of your build — especially when used alongside <>. Forking compilation has little effect on small builds but can help significantly when a single task compiles more than a thousand source files. diff --git a/platforms/documentation/docs/src/docs/userguide/overview/unused/quick_start.adoc b/platforms/documentation/docs/src/docs/userguide/overview/unused/quick_start.adoc deleted file mode 100644 index 1fbfec20510df..0000000000000 --- a/platforms/documentation/docs/src/docs/userguide/overview/unused/quick_start.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Copyright (C) 2024 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. - -[[quick_start]] -= Gradle Quick Start - -== Installing Gradle - -Most projects will start with an existing Gradle build which does not require the installation of Gradle. -However, if you are starting a project from scratch, and you need to install Gradle, check out the <>. - -== DPE University - -Want to get up and running with Gradle quickly? Take our free, self-paced Gradle Build Tool courses at DPE University: - -++++ -

- - LEARN - Take courses on DPE University > - -

-++++ - -== For Software Developers - -For software developers that need to build, test, and publish their app, or add dependencies to their build, get started here: - -=== 1. Core Concepts - -[sidebar] -_Description_: *Learn how to invoke tasks and add dependencies.* + -_Training level_: **Beginner** + -_Reading time_: **25 minutes** + -< Read Core Concepts >> - -=== 2. Hands-on Tutorial - -[sidebar] -_Description_: *Initialize a Gradle build for a basic Java App.* + -_Training level_: **Beginner** + -_Training time_: **45 minutes** + -< Start the Tutorial >> - -== For Build Engineers and Plugin Developers - -Build engineers and plugin developers that are ready to configure custom build logic or write their own plugins should start here: - -=== 1. Core Concepts - -[sidebar] -_Description_: *Learn to configure builds, create tasks, and write plugins.* + -_Training level_: **Intermediate** + -_Reading time_: **35 minutes** + -< Read Core Concepts >> - -=== 2. Hands-on Tutorial - -[sidebar] -_Description_: *Initialize a Gradle project and create a basic plugin.* + -_Training level_: **Intermediate** + -_Training time_: **55 minutes** + -< Start the Tutorial >> - -[[reference]] -=== 3. API Reference - -Gradle's API references can be found in the links below: - -- link:{javadocPath}/index.html[Javadocs^] -- link:{groovyDslPath}/index.html[Groovy DSL Reference^] -- link:{kotlinDslPath}/index.html[Kotlin DSL Reference^] diff --git a/platforms/documentation/docs/src/docs/userguide/overview/userguide.adoc b/platforms/documentation/docs/src/docs/userguide/overview/userguide.adoc index 66a244bc0306a..ae0f1fdc4c758 100644 --- a/platforms/documentation/docs/src/docs/userguide/overview/userguide.adoc +++ b/platforms/documentation/docs/src/docs/userguide/overview/userguide.adoc @@ -120,7 +120,6 @@ Gradle user manual and DSL reference manual are licensed under link:https://crea == Copyright -Copyright © 2024 Gradle, Inc. All rights reserved. -Gradle is a trademark of Gradle, Inc. +© 2025 Gradle, Inc. Gradle®, Develocity®, Build Scan®, and the Gradlephant logo are registered trademarks of Gradle, Inc. On this resource, "Gradle" typically means "Gradle Build Tool" and does not reference Gradle, Inc. and/or its subsidiaries. For inquiries related to commercial use or licensing, contact Gradle Inc. directly. diff --git a/platforms/documentation/docs/src/docs/userguide/platforms/jvm/toolchains.adoc b/platforms/documentation/docs/src/docs/userguide/platforms/jvm/toolchains.adoc index f13399c1e004d..835832c9d7d4c 100644 --- a/platforms/documentation/docs/src/docs/userguide/platforms/jvm/toolchains.adoc +++ b/platforms/documentation/docs/src/docs/userguide/platforms/jvm/toolchains.adoc @@ -14,6 +14,7 @@ [[toolchains]] = Toolchains for JVM projects +:keywords: jdk, toolchain Working on multiple projects can require interacting with multiple versions of the Java language. Even within a single project different parts of the codebase may be fixed to a particular language level due to backward compatibility requirements. diff --git a/platforms/documentation/docs/src/docs/userguide/platforms/native/native_software.adoc b/platforms/documentation/docs/src/docs/userguide/platforms/native/native_software.adoc index bcbbe2567e149..1b46d424ff982 100644 --- a/platforms/documentation/docs/src/docs/userguide/platforms/native/native_software.adoc +++ b/platforms/documentation/docs/src/docs/userguide/platforms/native/native_software.adoc @@ -160,7 +160,7 @@ Gradle uses the single build worker pool to concurrently compile and link native By default, the worker pool size is determined by the number of available processors on the build machine (as reported to the build JVM). To explicitly set the number of workers use the `--max-workers` command-line option or `org.gradle.workers.max` system property. There is generally no need to change this setting from its default. -The build worker pool is shared across all build tasks. This means that when using <>, the maximum number of concurrent individual compilation operations does not increase. For example, if the build machine has 4 processing cores and 10 projects are compiling in parallel, Gradle will only use 4 total workers, not 40. +The build worker pool is shared across all build tasks. This means that when using <>, the maximum number of concurrent individual compilation operations does not increase. For example, if the build machine has 4 processing cores and 10 projects are compiling in parallel, Gradle will only use 4 total workers, not 40. [[sec:building_a_library]] == Building a library diff --git a/platforms/documentation/docs/src/docs/userguide/redirects/bp_dependencies.adoc b/platforms/documentation/docs/src/docs/userguide/redirects/bp_dependencies.adoc new file mode 100644 index 0000000000000..5f3570623e526 --- /dev/null +++ b/platforms/documentation/docs/src/docs/userguide/redirects/bp_dependencies.adoc @@ -0,0 +1,3 @@ +++++ + +++++ diff --git a/platforms/documentation/docs/src/docs/userguide/redirects/bp_general.adoc b/platforms/documentation/docs/src/docs/userguide/redirects/bp_general.adoc new file mode 100644 index 0000000000000..1fbd9e56edb62 --- /dev/null +++ b/platforms/documentation/docs/src/docs/userguide/redirects/bp_general.adoc @@ -0,0 +1,3 @@ +++++ + +++++ diff --git a/platforms/documentation/docs/src/docs/userguide/redirects/bp_tasks.adoc b/platforms/documentation/docs/src/docs/userguide/redirects/bp_tasks.adoc new file mode 100644 index 0000000000000..3854e56928807 --- /dev/null +++ b/platforms/documentation/docs/src/docs/userguide/redirects/bp_tasks.adoc @@ -0,0 +1,3 @@ +++++ + +++++ diff --git a/platforms/documentation/docs/src/docs/userguide/redirects/declaring_dependencies_between_subprojects.adoc b/platforms/documentation/docs/src/docs/userguide/redirects/declaring_dependencies_between_subprojects.adoc new file mode 100644 index 0000000000000..f1186fc847598 --- /dev/null +++ b/platforms/documentation/docs/src/docs/userguide/redirects/declaring_dependencies_between_subprojects.adoc @@ -0,0 +1,3 @@ +++++ + +++++ diff --git a/platforms/documentation/docs/src/docs/userguide/reference/core-plugins/pmd_plugin.adoc b/platforms/documentation/docs/src/docs/userguide/reference/core-plugins/pmd_plugin.adoc index 59e5302cc032e..eda921beb3a0c 100644 --- a/platforms/documentation/docs/src/docs/userguide/reference/core-plugins/pmd_plugin.adoc +++ b/platforms/documentation/docs/src/docs/userguide/reference/core-plugins/pmd_plugin.adoc @@ -89,7 +89,7 @@ include::sample[dir="snippets/codeQuality/codeQuality/groovy",files="build.gradl [NOTE] ==== -This configuration is internal to PMD and is not linked to <> used by Gradle. +This configuration is internal to PMD and is not linked to <> used by Gradle. It means that you have to pay attention to the value entered here and make sure it still makes sense in a multi project build. This is because parallel Gradle task execution could result in different PMD tasks from different projects running in parallel. If multiple PMD tasks execute simultaneously in n projects, then up to a maximum of (n * `thread`) PMD threads could run at the same time. diff --git a/platforms/documentation/docs/src/docs/userguide/reference/isolated_projects.adoc b/platforms/documentation/docs/src/docs/userguide/reference/isolated_projects.adoc index dff59652607db..44987c0a051fc 100644 --- a/platforms/documentation/docs/src/docs/userguide/reference/isolated_projects.adoc +++ b/platforms/documentation/docs/src/docs/userguide/reference/isolated_projects.adoc @@ -15,6 +15,7 @@ :gradle-issues: https://github.com/gradle/gradle/issues/ = Isolated Projects +:keywords: ip Isolated Projects is a pre-alpha Gradle feature that extends the configuration cache to further improve performance, particularly the performance of Android Studio and IDEA sync. diff --git a/platforms/documentation/docs/src/docs/userguide/releases/compatibility.adoc b/platforms/documentation/docs/src/docs/userguide/releases/compatibility.adoc index 7d9343bb5f526..32b3199121f88 100644 --- a/platforms/documentation/docs/src/docs/userguide/releases/compatibility.adoc +++ b/platforms/documentation/docs/src/docs/userguide/releases/compatibility.adoc @@ -21,8 +21,8 @@ Versions not listed here may or may not work. == Java Runtime Gradle runs on the Java Virtual Machine (JVM), which is often provided by either a JDK or JRE. -A JVM version between 8 and 23 is required to execute Gradle. -JVM 24 and later versions are not yet supported. +A JVM version between 8 and 24 is required to execute Gradle. +JVM 25 and later versions are not yet supported. Executing the Gradle daemon with JVM 16 or earlier has been deprecated and will become an error in Gradle 9.0. The Gradle wrapper, Gradle client, Tooling API client, and TestKit client will remain compatible with JVM 8. diff --git a/platforms/documentation/docs/src/docs/userguide/releases/feature_lifecycle.adoc b/platforms/documentation/docs/src/docs/userguide/releases/feature_lifecycle.adoc index fbee3a69fdbb1..101c1dbf8409f 100644 --- a/platforms/documentation/docs/src/docs/userguide/releases/feature_lifecycle.adoc +++ b/platforms/documentation/docs/src/docs/userguide/releases/feature_lifecycle.adoc @@ -14,6 +14,7 @@ [[feature_lifecycle]] = The Feature Lifecycle +:keywords: incubating Gradle is under constant development. New versions are delivered on a regular and frequent basis (approximately every six weeks) as described in <<#eol_support,the section on end-of-life support>>. diff --git a/platforms/documentation/docs/src/docs/userguide/releases/installation.adoc b/platforms/documentation/docs/src/docs/userguide/releases/installation.adoc index dd6d8b9caa422..b597316017e24 100644 --- a/platforms/documentation/docs/src/docs/userguide/releases/installation.adoc +++ b/platforms/documentation/docs/src/docs/userguide/releases/installation.adoc @@ -14,6 +14,7 @@ [[installation]] = Installing Gradle +:keywords: install [[gs:installation]] == Gradle Installation diff --git a/platforms/documentation/docs/src/docs/userguide/releases/migrating/migrating_from_ant.adoc b/platforms/documentation/docs/src/docs/userguide/releases/migrating/migrating_from_ant.adoc index 969fc5a43faf8..d1a3642f2d5d4 100644 --- a/platforms/documentation/docs/src/docs/userguide/releases/migrating/migrating_from_ant.adoc +++ b/platforms/documentation/docs/src/docs/userguide/releases/migrating/migrating_from_ant.adoc @@ -504,7 +504,7 @@ include::sample[dir="snippets/antMigration/multiProject/kotlin",files="web/build include::sample[dir="snippets/antMigration/multiProject/groovy",files="web/build.gradle[]"] ==== + -This is not as robust or powerful as Gradle's <>, but it solves the immediate problem without big changes to the build. +This is not as robust or powerful as Gradle's <>, but it solves the immediate problem without big changes to the build. Just be careful to remove or override any dependencies on tasks that delegate to other subprojects, like the `buildRequiredProjects` task. 5. Identify the projects that have no dependencies on other projects and migrate them to idiomatic Gradle builds scripts. + diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/build_environment.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/build_environment.adoc index 39118fa39b81e..e3ee0099857cd 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/build_environment.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/build_environment.adoc @@ -14,7 +14,7 @@ [[build_environment]] = Configuring the Build Environment -:keywords: properties,gradle,system,project,environment,variables +:keywords: properties, system, project, environment, variables, https.protocols, gradle.properties, gradle.user.home, gradle.wrapperPassword, gradle.wrapperUser, org.gradle, gradle, java_home, gradle_opts, java_opts, gradle_libs_repo_override Configuring the build environment is a powerful way to customize the build process. There are many mechanisms available. @@ -382,7 +382,7 @@ The values are not case-sensitive. _Default is `lifecycle` level._ `org.gradle.parallel=(true,false)`:: -When configured, Gradle will fork up to `org.gradle.workers.max` JVMs to execute <>. +When configured, Gradle will fork up to `org.gradle.workers.max` JVMs to execute <>. + _Default is `false`._ diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/directory_layout.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/directory_layout.adoc index 8c5f2bad4de3c..9483bc9a5b7d6 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/directory_layout.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/directory_layout.adoc @@ -14,7 +14,7 @@ [[directory_layout]] = Gradle-managed Directories -:keywords: gradle,user,home,project,root +:keywords: gradle, user, home, project, root, directory, gradle_home, gradle_user_home Gradle uses two main directories to perform and manage its work: diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/command_line_interface.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/command_line_interface.adoc index 832e57b0f0114..6fad2015ea28a 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/command_line_interface.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/command_line_interface.adoc @@ -14,6 +14,7 @@ [[command_line_interface_reference]] = Command-Line Interface Reference +:keywords: cli, clean, check, projects, tasks, rerun-tasks, continue, build-cache, no-build-cache, configuration-cache, no-configuration-cache, configuration-cache-problems, configure-on-demand, no-configure-on-demand, max-workers, parallel, no-parallel, priority, profile, scan, watch-fs, no-watch-fs, help, version, show-version, full-stacktrace, stacktrace, org.gradle.debug, org.gradle.debug.host, org.gradle.debug.port, org.gradle.debug.server, org.gradle.debug.suspend, org.gradle.daemon.debug, project-cache-dir, system-prop, init-script, project-prop, org.gradle.jvmargs, org.gradle.java.home, gradle-user-home, dependency-verification, write-verification-metadata, refresh-keys, export-keys, include-build, offline, refresh-dependencies, dry-run, continuous, write-locks, update-locks , no-rebuild, org.gradle.warning.mode, warning-mode, no-problems-report, problems-report, org.gradle.console, console, org.gradle.logging.level, quiet, warn, info, debug, daemon, no-daemon, foreground, status, stop, org.gradle.daemon.idletimeout, exclude-task, distribution-type, gradle-distribution-url, gradle-distribution-sha256-sum, gradle-version The command-line interface is the **primary method of interacting with Gradle**. @@ -602,7 +603,7 @@ Toggles configure-on-demand. Only relevant projects are configured in this build Sets the maximum number of workers that Gradle may use. _Default is number of processors_. `--parallel`, `--no-parallel`:: -Build projects in parallel. For limitations of this option, see <>. _Default is off_. +Build projects in parallel. For limitations of this option, see <>. _Default is off_. `--priority`:: Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Values are `normal` or `low`. _Default is normal_. diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/continuous_builds.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/continuous_builds.adoc index e164b00e7cfb8..ebc60d1bed1de 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/continuous_builds.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/continuous_builds.adoc @@ -14,7 +14,6 @@ [[continuous_builds]] = Continuous Builds -:keywords: continuous,builds 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. diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/file_system_watching.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/file_system_watching.adoc index fb56abe4643bf..2610a36eb2695 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/file_system_watching.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/file_system_watching.adoc @@ -14,7 +14,7 @@ [[sec:daemon_watch_fs]] = File System Watching -:keywords: file,system,watching +:keywords: file, system, vfs, watch-fs, no-watch-fs,org.gradle.vfs.watch, org.gradle.vfs.verbose Gradle maintains a Virtual File System (VFS) to calculate what needs to be rebuilt on repeat builds of a project. By watching the file system, Gradle keeps the VFS current between builds. diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_daemon.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_daemon.adoc index d2ce07f861c51..b0d7dcf650f4c 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_daemon.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_daemon.adoc @@ -14,7 +14,7 @@ [[gradle_daemon]] = Gradle Daemon -:keywords: daemon +:keywords: daemon, status, jps, no-daemon, stop, org.gradle.daemon, updateDaemonJvm, gradle-daemon-jvm.properties, jvm-version, jvm-vendor A daemon is a computer program that runs as a background process rather than being under the direct control of an interactive user. diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_wrapper.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_wrapper.adoc index c8dafd6df5d4b..b5356cde4895a 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_wrapper.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/gradle_wrapper.adoc @@ -14,7 +14,7 @@ [[gradle_wrapper_reference]] = Gradle Wrapper Reference -:keywords: wrapper +:keywords: wrapper, distributionUrl, gradle-version, systemProp.gradle.wrapperUser, systemProp.gradle.wrapperPassword, gradle-wrapper.jar, gradle-wrapper.properties, gradlew, gradlew.bat, gradle-version, distribution-type, gradle-distribution-url, gradle-distribution-sha256-sum, network-timeout, no-validate-url, validate-url, The **recommended way to execute any Gradle build** is with the help of the Gradle Wrapper (referred to as "Wrapper"). diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/features/logging.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/features/logging.adoc index 912f35680a493..c7268b97271b2 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/features/logging.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/features/logging.adoc @@ -14,6 +14,7 @@ [[logging]] = Logging +:keywords: error, quiet, warning, lifecycle, info, warn, org.gradle.logging.level, stacktrace, org.gradle.logging.stacktrace, full-stacktrace The build log is the primary way Gradle communicates what's happening during a build. Clear logging helps you quickly understand your build status, identify issues, and troubleshoot effectively. diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/introduction/build_file_basics.adoc b/platforms/documentation/docs/src/docs/userguide/running-builds/introduction/build_file_basics.adoc index e63511ddf2f56..e3d2639b337e0 100644 --- a/platforms/documentation/docs/src/docs/userguide/running-builds/introduction/build_file_basics.adoc +++ b/platforms/documentation/docs/src/docs/userguide/running-builds/introduction/build_file_basics.adoc @@ -99,7 +99,7 @@ include::sample[dir="snippets/init/generated/kotlin",files="app/build.gradle.kts include::sample[dir="snippets/init/generated/groovy",files="app/build.gradle[tags=init-app]"] ==== -In this example, the main class (i.e., the point where the program's execution begins) is `com.example.Main`. +In this example, the main class (i.e., the point where the program's execution begins) is `org.example.App`. Build scripts are evaluated during the configuration phase of a build, and they serve as the main entry point for defining a (sub)project’s build logic. In addition to applying plugins and setting convention properties, build scripts can: diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/unused/config_gradle.adoc b/platforms/documentation/docs/src/docs/userguide/unused/config_gradle.adoc similarity index 100% rename from platforms/documentation/docs/src/docs/userguide/running-builds/unused/config_gradle.adoc rename to platforms/documentation/docs/src/docs/userguide/unused/config_gradle.adoc diff --git a/platforms/documentation/docs/src/docs/userguide/running-builds/unused/gradle_ides.adoc b/platforms/documentation/docs/src/docs/userguide/unused/gradle_ides.adoc similarity index 100% rename from platforms/documentation/docs/src/docs/userguide/running-builds/unused/gradle_ides.adoc rename to platforms/documentation/docs/src/docs/userguide/unused/gradle_ides.adoc diff --git a/platforms/documentation/docs/src/main/resources/footer.html b/platforms/documentation/docs/src/main/resources/footer.html index 2aa0ead22058e..e76eba74489b0 100644 --- a/platforms/documentation/docs/src/main/resources/footer.html +++ b/platforms/documentation/docs/src/main/resources/footer.html @@ -42,8 +42,8 @@

Authoring Gradle Builds

Reference