// Copyright (C) 2025 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.

[[best_practices_general]]
= General Gradle Best Practices

[[use_kotlin_dsl]]
== Use Kotlin DSL

Prefer the Kotlin DSL (`build.gradle.kts`) over the Groovy DSL (`build.gradle`) when authoring new builds or creating new subprojects in existing builds.

=== Explanation

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.

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].

=== References

- <<kotlin_dsl.adoc#kotdsl:kotlin_dsl,Kotlin DSL Primer>>

=== Tags

<<tags_reference.adoc#tag:kotlin-dsl,`#kotlin-dsl`>>

[[use_latest_minor_versions]]
== Use the Latest Minor Version of Gradle

Stay on the latest minor version of the major Gradle release you're using, and regularly update your plugins to the latest compatible versions.

=== Explanation

Gradle follows a fairly predictable, time-based release cadence.
Only the latest minor version of the current and previous major release is actively supported.

We recommend the following strategy:

* Try upgrading directly to the latest minor version of your current major Gradle release.
* If that fails, upgrade one minor version at a time to isolate regressions or compatibility issues.

Each new minor version includes:

* Performance and stability improvements.
* Deprecation warnings that help you prepare for the next major release.
* Fixes for known bugs and security vulnerabilities.

Use the `wrapper` task to update your project:

[source, bash]
----
./gradlew wrapper --gradle-version <version>
----

You can also install the latest Gradle versions easily using tools like link:https://sdkman.io/[SDKMAN!] or link:https://brew.sh/[Homebrew], depending on your platform.

=== Plugin Compatibility

Always use the latest compatible version of each plugin:

* Upgrade Gradle before plugins.
* Test plugin compatibility using link:https://slack.engineering/shadow-jobs/[shadow jobs].
* Consult changelogs when updating.

Subscribe to the Gradle link:https://newsletter.gradle.org/[newsletter] to stay informed about new Gradle releases, features, and plugins.

=== References

- <<upgrading_version_9.adoc#upgrading_version_9,Upgrade Guide>>

=== Tags

<<tags_reference.adoc#tag:plugins,`#plugins`>>

[[use_the_plugins_block]]
== Apply Plugins Using the `plugins` Block

You should always use the `plugins` block to <<plugin_basics.adoc#applying_plugins,apply plugins>> in your build scripts.

=== Explanation

The `plugins` block is the preferred way to apply plugins in Gradle.
The plugins API allows Gradle to better manage the loading of plugins and it is both more concise and less error-prone than adding dependencies to the buildscript's classpath explicitly in order to use the `apply` method.

It allows Gradle to optimize the loading and reuse of plugin classes and helps inform tools about the potential properties and values in extensions the plugins will add to the build script.
It is constrained to be idempotent (produce the same result every time) and side effect-free (safe for Gradle to execute at any time).

=== Example

==== Don't Do This

====
include::sample[dir="snippets/bestPractices/usePluginsBlock-avoid/kotlin",files="build.gradle.kts[tags=avoid-this]"]
include::sample[dir="snippets/bestPractices/usePluginsBlock-avoid/groovy",files="build.gradle[tags=avoid-this]"]
====

<1> *Declare a Repository*: To use the legacy plugin application syntax, you need to explicitly tell Gradle where to find a plugin.
<2> *Declare a Plugin Dependency*: To use the legacy plugin application syntax with third-party plugins, you need to explicitly tell Gradle the full coordinates of the plugin.
<3> *Apply a Core Plugin*: This is very similar using either method.
<4> *Apply a Third-Party Plugin*: The syntax is the same as for core Gradle plugins, but the version is not present at the point of application in your buildscript.

==== Do This Instead

++++
<div style="text-align: right;">
  <a class="download-project-link"
     data-base-path="https://github.com/gradle/gradle/tree/master/platforms/documentation/docs/src/snippets/bestPractices/usePluginsBlock-do/"
     href="https://download-directory.github.io/?url=https://github.com/gradle/gradle/tree/master/platforms/documentation/docs/src/snippets/bestPractices/usePluginsBlock-do/kotlin">
    <img src="https://img.shields.io/badge/Download%20Project-GitHub-blue?logo=github&style=flat" alt="Download"/>
  </a>
</div>
++++

====
include::sample[dir="snippets/bestPractices/usePluginsBlock-do/kotlin",files="build.gradle.kts[tags=do-this]"]
include::sample[dir="snippets/bestPractices/usePluginsBlock-do/groovy",files="build.gradle[tags=do-this]"]
====

<1> *Apply a Core Plugin*: This is very similar using either method.
<2> *Apply a Third-Party Plugin*: You specify the version using method chaining in the `plugins` block itself.

=== References

- <<plugins_intermediate.adoc#using_plugins,Using Plugins>>

=== Tags

`<<tags_reference.adoc#tag:structuring-builds,#structuring-builds>>`

[[do_not_use_internal_apis]]
== Do Not Use Internal APIs

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.

=== Explanation

Using internal APIs is inherently risky and can cause significant problems during upgrades.
Gradle and many plugins (such as Android Gradle Plugin and Kotlin Gradle Plugin) treat these internal APIs as subject to unannounced breaking changes during any new Gradle release, even during minor releases.
There have been numerous cases where even highly experienced plugin developers have been bitten by their usage of such APIs leading to unexpected breakages for their users.

If you require specific functionality that is missing, it’s best to submit a feature request.
As a temporary workaround consider copying the necessary code into your own codebase and extending a Gradle public type with your own custom implementation using the copied code.

=== Example

==== Don't Do This

====
include::sample[dir="snippets/bestPractices/avoidInternal-avoid/kotlin",files="build.gradle.kts[tags=avoid-this]"]
include::sample[dir="snippets/bestPractices/avoidInternal-avoid/groovy",files="build.gradle[tags=avoid-this]"]
====

<1> Casting to `AttributeContainerInternal` and using `toMap()` should be avoided as it relies on an internal API.

==== Do This Instead

++++
<div style="text-align: right;">
  <a class="download-project-link"
     data-base-path="https://github.com/gradle/gradle/tree/master/platforms/documentation/docs/src/snippets/bestPractices/avoidInternal-do/"
     href="https://download-directory.github.io/?url=https://github.com/gradle/gradle/tree/master/platforms/documentation/docs/src/snippets/bestPractices/avoidInternal-do/kotlin">
    <img src="https://img.shields.io/badge/Download%20Project-GitHub-blue?logo=github&style=flat" alt="Download"/>
  </a>
</div>
++++

====
include::sample[dir="snippets/bestPractices/avoidInternal-do/kotlin",files="build.gradle.kts[tags=do-this]"]
include::sample[dir="snippets/bestPractices/avoidInternal-do/groovy",files="build.gradle[tags=do-this]"]
====

<1> Implementing your own version of `toMap()` that only uses public APIs is a lot more robust.

=== References

- link:https://docs.gradle.org/current/javadoc/[Gradle API]

=== Tags

<<tags_reference.adoc#tag:upgrades,`#upgrades`>>


[[use_the_gradle_properties_file]]
== Set build flags in `gradle.properties`

Set Gradle build property flags in the `gradle.properties` file.

=== Explanation

Instead of using command-line options or environment variables, set build flags in the root project's `gradle.properties` file.

Gradle comes with a long list of <<build_environment.adoc#sec:gradle_configuration_properties,Gradle properties>>, which have names that begin with `org.gradle` and can be used to configure the behavior of the build tool.
These properties can have a **major impact** on build performance, so it’s important to understand how they work.

You should not rely on supplying these properties via the command-line for every Gradle invocation.
Providing these properties via the command line is intended for short-term testing and debugging purposes, but it’s prone to being forgotten or inconsistently applied across environments.
A permanent, idiomatic location to set and share these properties is in the `gradle.properties` file located in the root project directory.
This file should be added to source control in order to share these properties across different machines and between developers.

You should understand the default values of the properties your build uses and avoid explicitly setting properties to those defaults.
Any change to a property's default value in Gradle will follow the standard <<feature_lifecycle.adoc#backwards_compatibility,deprecation cycle>>, and users will be properly notified.

NOTE: Properties set this way are not inherited across build boundaries when using <<composite_builds.adoc#composite_builds,composite builds>>.

=== Example

==== Don't Do This

[.multi-language-sample]
=====
[source, kotlin]
----
├── build.gradle.kts
└── settings.gradle.kts
----
=====
[.multi-language-sample]
=====
[source, groovy]
----
├── build.gradle
└── settings.gradle
----
=====

====
include::sample[dir="snippets/bestPractices/useTheGradlePropertiesFile-avoid/kotlin",files="build.gradle.kts[tags=avoid-this]"]
include::sample[dir="snippets/bestPractices/useTheGradlePropertiesFile-avoid/groovy",files="build.gradle[tags=avoid-this]"]
====

This build is run with `gradle run -Dorg.gradle.continue=true`, so that the failure of the `first` task does **not** prevent the `second` task from executing.

This relies on person running the build to remember to set this property, which is error prone and not portable across different machines and environments.

==== Do This Instead

[.multi-language-sample]
=====
[source, kotlin]
----
├── build.gradle.kts
└── gradle.properties
└── settings.gradle.kts
----
=====
[.multi-language-sample]
=====
[source, groovy]
----
├── build.gradle
└── gradle.properties
└── settings.gradle
----
=====

.gradle.properties
[source,properties]
----
include::{snippetsPath}/bestPractices/useTheGradlePropertiesFile-do/kotlin/gradle.properties[tag=do-this]
----

This build sets the `org.gradle.continue` property in the `gradle.properties` file.

Now it can be executed using only `gradle run`, and the continue property will always be set automatically across all environments.

=== References

- <<build_environment.adoc#sec:gradle_configuration_properties,Gradle properties>>

=== Tags

<<tags_reference.adoc#tag:properties,`#properties`>>
