// Copyright 2021 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.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.

[[upgrading_version_7]]
= Upgrading your build from Gradle 7.x to the latest

This chapter provides the information you need to migrate your Gradle 7.x builds to the latest Gradle release. For migrating from Gradle 4.x, 5.x, or 6.x, see the <<upgrading_version_6.adoc#upgrading_version_6, older migration guide>> first.

We recommend the following steps for all users:

. Try running `gradle help --scan` and view the https://gradle.com/enterprise/releases/2018.4/#identify-usages-of-deprecated-gradle-functionality[deprecations view] of the generated build scan.
+
image::deprecations.png[Deprecations View of a Gradle Build Scan]
+
This is so that you can see any deprecation warnings that apply to your build.
+
Alternatively, you could run `gradle help --warning-mode=all` to see the deprecations in the console, though it may not report as much detailed information.
. Update your plugins.
+
Some plugins will break with this new version of Gradle, for example because they use internal APIs that have been removed or changed. The previous step will help you identify potential problems by issuing deprecation warnings when a plugin does try to use a deprecated part of the API.
+
. Run `gradle wrapper --gradle-version {gradleVersion}` to update the project to {gradleVersion}.
. Try to run the project and debug any errors using the <<troubleshooting.adoc#troubleshooting, Troubleshooting Guide>>.

[[changes_7.4]]
== Upgrading from 7.3 and earlier

=== Potential breaking changes

==== Updates to default tool integration versions

- PMD has been updated to https://github.com/pmd/pmd/releases/tag/pmd_releases%2F6.39.0[PMD 6.39.0].

=== Deprecations

[[adoptopenjdk_download]]
==== AdoptOpenJDK toolchain download

Following the move from AdoptOpenJDK to Adoptium, under the Eclipse foundation, it is no longer possible to download an AdoptOpenJDK build from their end point.
Instead, an Eclipse Temurin or IBM Semeru build is returned.

Gradle 7.4+ will now emit a deprecation warning when the AdoptOpenJDK vendor is specified in the <<toolchains.adoc#sec:vendors,toolchain specification>> and it is used by auto provisioning.
If you must use AdoptOpenJDK, you should turn off auto-download. If an Eclipse Temurin or IBM Semeru build works for you, specify `JvmVendorSpec.ADOPTIUM` or `JvmVendorSpec.IBM_SEMERU` as the vendor or leave the vendor unspecified.

[[empty_directories_file_tree]]
==== File trees and empty directory handling

When using `@link:{javadocPath}/org/gradle/api/tasks/SkipWhenEmpty.html[SkipWhenEmpty]` on an input file collection, Gradle skips the task when it determines that the input is empty.
If the input file collection consists only of file trees, Gradle ignores directories for the emptiness check.
Though when checking for changes to the input file collection, Gradle only ignores directories when the `@link:{javadocPath}/org/gradle/api/tasks/IgnoreEmptyDirectories.html[IgnoreEmptyDirectories]` annotation is present.

Gradle will now ignore directories for both the `@SkipWhenEmpty` check and for determining changes consistently.
Until Gradle 8.0, Gradle will detect if an input file collection annotated with `@SkipWhenEmpty` consists only of file trees and then ignore directories automatically.
Moreover, Gradle will issue a deprecation warning to advise the user that the behavior will change in Gradle 8.0, and that the input property should be annotated with `@IgnoreEmptyDirectories`.
To ignore directories in Gradle 8.0 and later, the input property needs to be annotated with `@IgnoreEmptyDirectories`.

Finally, using `@link:{javadocPath}/org/gradle/api/tasks/InputDirectory.html[InputDirectory]` implies `@IgnoreEmptyDirectories`, so no changes are necessary when using this annotation.
The same is true for `@link:{javadocPath}/org/gradle/api/tasks/TaskInputs.html#dir-java.lang.Object-[inputs.dir()]` when registering an input directory via the runtime API.

[[lazypublishartifact_fileresolver]]
==== Using LazyPublishArtifact without a FileResolver is deprecated

When using a LazyPublishArtifact without a FileResolver, a different file resolution strategy is used, which duplicates
some logic in the FileResolver. To improve consistency, LazyPublishArtifact should be used with a FileResolver, and will
require it in the future.

This also affects other internal APIs that use LazyPublishArtifact, which now also have deprecation warnings where needed.

[[tar_tree_no_backing_file]]
==== TAR trees from resources without backing files

It is possible to create TAR trees from arbitrary resources.
If the resource is not created via `project.resources`, then it may not have a backing file.
Creating a TAR tree from a resource with no backing file has been deprecated.
Instead, convert the resource to a file and use `project.tarTree()` on the file.
To convert the resource to a file you can use a custom task or use dependency management to download the file via a URL.
This way, Gradle is able to apply optimizations like up-to-date checks instead of re-running the logic to create the resource every time.

[[unique_attribute_sets]]
==== Unique attribute sets

The set of link:{javadocPath}/org/gradle/api/attribute/Attribute.html[Attribute]s associated with a _consumable_ configuration within a project, must be unique across all other configurations within that project _which share the same set of link:{javadocPath}/org/gradle/api/capabilities/Capability.html[Capability]s.  This will be checked at the end of configuring variant configurations, as they are locked against further mutation.

If the set of attributes is shared across configurations, consider adding an additional attribute to one of the variants for the sole purpose of disambiguation.

[[for_use_at_configuration_time_deprecation]]
==== `Provider#forUseAtConfigurationTime()` has been deprecated

link:{javadocPath}/org/gradle/api/provider/Provider.html#forUseAtConfigurationTime--[Provider#forUseAtConfigurationTime] is now deprecated and scheduled for removal in Gradle 9.0. Clients should simply remove the call.

The call was mandatory on providers of external values such as link:{javadocPath}/org/gradle/api/provider/ProviderFactory.html#systemProperty-java.lang.String-[system properties], link:{javadocPath}/org/gradle/api/provider/ProviderFactory.html#environmentVariable-java.lang.String-[environment variables], link:{javadocPath}/org/gradle/api/provider/ProviderFactory.html#gradleProperty-java.lang.String-[Gradle properties] and link:{javadocPath}/org/gradle/api/provider/ProviderFactory.html#fileContents-org.gradle.api.file.RegularFile-[file contents] meant to be used at configuration time together with the configuration cache feature.

Starting with version 7.4 Gradle will implicitly treat an external value used at configuration time as a configuration cache input.

Clients are also free to use standard Java APIs such as `System#getenv` to read environment variables, `System#getProperty` to read system properties as well as Gradle APIs such as link:{javadocPath}/org/gradle/api/provider/ProviderFactory.html#systemProperty-java.lang.String-[`Project#property(String)`] and link:{javadocPath}/org/gradle/api/Project.html#findProperty-java.lang.String-[`Project#findProperty(String)`] to read Gradle properties at configuration time. The `Provider` based APIs are still the recommended way to connect external values to task inputs for maximum configuration cache reuse.

==== `ConfigurableReport#setDestination(org.gradle.api.provider.Provider<java.io.File>)` has been deprecated

link:{javadocPath}/org/gradle/api/reporting/ConfigurableReport.html#setDestination-org.gradle.api.provider.Provider-[`ConfigurableReport#setDestination(org.gradle.api.provider.Provider<java.io.File>)`] is now deprecated and scheduled for removal in Gradle 8.0.

Use link:{javadocPath}/org/gradle/api/reporting/Report.html#getOutputLocation--[`Report#getOutputLocation().set(...)`] instead.

[[task_execution_events]]
==== Task execution listeners and events

The Gradle configuration cache does not support listeners and events that have direct access to `Task` and `Project` instances,
which allows Gradle to execute tasks in parallel and to store the minimal amount of data in the configuration cache.
In order to move towards an API that is consistent whether the configuration cache is enabled or not,
the following APIs are deprecated and will be removed or be made an error in Gradle 8.0:

- Interface link:{javadocPath}/org/gradle/api/execution/TaskExecutionListener.html[TaskExecutionListener]
- Interface link:{javadocPath}/org/gradle/api/execution/TaskActionListener.html[TaskActionListener]
- Method link:{javadocPath}/org/gradle/api/execution/TaskExecutionGraph.html#addTaskExecutionListener-org.gradle.api.execution.TaskExecutionListener-[TaskExecutionGraph.addTaskExecutionListener()]
- Method link:{javadocPath}/org/gradle/api/execution/TaskExecutionGraph.html#removeTaskExecutionListener-org.gradle.api.execution.TaskExecutionListener-[TaskExecutionGraph.removeTaskExecutionListener()]
- Method link:{javadocPath}/org/gradle/api/execution/TaskExecutionGraph.html#beforeTask-org.gradle.api.Action-[TaskExecutionGraph.beforeTask()]
- Method link:{javadocPath}/org/gradle/api/execution/TaskExecutionGraph.html#afterTask-org.gradle.api.Action-[TaskExecutionGraph.afterTask()]
- Registering TaskExecutionListener, TaskActionListener, TestListener, TestOutputListener via link:{javadocPath}/org/gradle/api/invocation/Gradle.html#addListener-java.lang.Object-[Gradle.addListener()]

See the <<configuration_cache#config_cache:requirements:build_listeners,configuration cache chapter>> for details on how to migrate
these usages to APIs that are supported by the configuration cache.

[[build_finished_events]]
==== Build finished events

Build finished listeners are not supported by the Gradle configuration cache. And so, the following API are deprecated and will be
removed in Gradle 8.0:

- Method link:{javadocPath}/org/gradle/api/invocation/Gradle.html#buildFinished-org.gradle.api.Action-[Gradle.buildFinished()]
- Method link:{javadocPath}/org/gradle/BuildListener.html#buildFinished-org.gradle.BuildResult-[BuildListener.buildFinished()]

See the <<configuration_cache#config_cache:requirements:build_listeners,configuration cache chapter>> for details on how to migrate
these usages to APIs that are supported by the configuration cache.

[[task_project]]
==== Calling `Task#getProject()` from a task action

Calling link:{javadocPath}/org/gradle/api/Task.html#getProject--[Task.getProject()] from a task action at execution time is
now deprecated and will be made an error in Gradle 8.0.
This method can be used during configuration time, but it is recommended to avoid doing this.

See the <<configuration_cache#config_cache:requirements:use_project_during_execution,configuration cache chapter>> for details on
how to migrate these usages to APIs that are supported by the configuration cache.

[[task_dependencies]]
==== Calling `Task#getTaskDependencies()` from a task action

Calling link:{javadocPath}/org/gradle/api/Task.html#getTaskDependencies--[Task.getTaskDependencies()] from a task action at
execution time is now deprecated and will be made an error in Gradle 8.0.
This method can be used during configuration time, but it is recommended to avoid doing this.

See the <<configuration_cache#config_cache:requirements:use_project_during_execution,configuration cache chapter>> for details on
how to migrate these usages to APIs that are supported by the configuration cache.

[[undeclared_build_service_usage]]
==== Using a build service from a task without the corresponding `Task#usesService` declaration

Gradle needs the information so it can properly honor the build service lifecycle and its usage constraints.

This will become an error in a future Gradle version.

Check the <<build_services.adoc#using_a_build_service_from_a_task, Shared Build Services documentation>> for more information.

[[version_catalog_deprecations]]
==== VersionCatalog and VersionCatalogBuilder deprecations

Some methods in link:{javadocPath}/org/gradle/api/artifacts/VersionCatalog.html[VersionCatalog] and link:{javadocPath}/org/gradle/api/initialization/dsl/VersionCatalogBuilder.html[VersionCatalogBuilder] are now deprecated and scheduled for removal in Gradle 8.0. Specific replacements can be found in the JavaDoc of the affected methods.

These methods were changed to improve the consistency between the `libs.versions.toml` file and the API classes.

[[changes_7.3]]
== Upgrading from 7.2 and earlier

=== Potential breaking changes

==== Updates to bundled Gradle dependencies

- Kotlin has been updated to https://github.com/JetBrains/kotlin/releases/tag/v1.5.31[Kotlin 1.5.31].
- Groovy has been updated to https://groovy-lang.org/changelogs/changelog-3.0.9.html[Groovy 3.0.9].
- Ant has been updated to https://archive.apache.org/dist/ant/RELEASE-NOTES-1.10.11.html[Ant 1.10.11] to fix https://github.com/advisories/GHSA-q5r4-cfpx-h6fh[CVE-2021-36373] and https://github.com/advisories/GHSA-5v34-g2px-j4fw[CVE-2021-36374].
- Commons compress has been updated to https://commons.apache.org/proper/commons-compress/[Commons-compress 1.21] to fix https://github.com/advisories/GHSA-7hfm-57qf-j43q[CVE-2021-35515], https://github.com/advisories/GHSA-crv7-7245-f45f[CVE-2021-35516], https://github.com/advisories/GHSA-xqfj-vm6h-2x34[CVE-2021-35517] and https://github.com/advisories/GHSA-mc84-pj99-q6hh[CVE-2021-36090].

==== Application order of plugins in the `plugins` block

The order in which plugins in the `plugins` block were actually applied was inconsistent
and depended on how a plugin was added to the class path. Now the plugins are always applied
in the same order they are declared in the `plugins` block which in rare cases might change
behavior of existing builds.

==== Effects of exclusion on substituted dependencies in dependency resolution

Prior to this version, a dependency substitution target could not be excluded from a dependency graph.
This was caused by checking for exclusions prior to performing the substitution.
Now Gradle will also check for exclusion on the substitution result.

==== Version catalog

Generated accessors no longer give access to the type unsafe API.
You have to use the <<platforms.adoc#sub:type-unsafe-access-to-catalog,version catalog extension>> instead.

==== Toolchain support in Scala

When using <<scala_plugin.adoc#sec:scala_tasks,toolchains in Scala>>, the `-target` option of the Scala compiler will now be set automatically.
This means that using a version of Java that cannot be targeted by a version of Scala will result in an error.
Providing this flag in the compiler options will disable this behaviour and allow to use a higher Java version to compile for a lower bytecode target.

[[declare_unreadable_input_output]]
==== Declaring input or output directories which contain unreadable content

For up-to-date checks Gradle relies on tracking the state of the inputs and the outputs of a task.
Gradle used to ignore unreadable files in the input or outputs to support certain use-cases, although it cannot track their state.
Declaring input or output directories on tasks which contain unreadable content has been deprecated and these use-cases are now supported by declaring the task to be untracked.
Use the @link:{javadocPath}/org/gradle/api/tasks/UntrackedTask.html[UntrackedTask] annotation or the link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:doNotTrackState(java.lang.String)[Task.doNotTrackState()] method to declare a task as untracked.

When you are using a `link:{groovyDslPath}/org.gradle.api.tasks.Copy.html[Copy]` task for copying single files into a directory which contains unreadable files, use the method link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:doNotTrackState(java.lang.String)[Task.doNotTrackState()].

[[changes_7.2]]
== Upgrading from 7.1 and earlier

=== Potential breaking changes

==== Security changes to application start scripts and Gradle wrapper scripts

Due to https://github.com/gradle/gradle/security/advisories/GHSA-6j2p-252f-7mw8[CVE-2021-32751], `gradle`, `gradlew` and start scripts generated by Gradle's <<application_plugin.adoc#application_plugin,application plugin>> have been updated to avoid situations where these
scripts could be used for arbitrary code execution when an attacker is able to change environment variables.

You can use the latest version of Gradle to generate a `gradlew` script and use it to execute an older version of Gradle.

This should be a transparent for most users; however, there may be changes for Gradle builds that rely on the environment variables `JAVA_OPTS` or `GRADLE_OPTS` to pass parameters with complicated quote escaping.
Contact us if you suspect something has broken your build and you cannot find a solution.

==== Updates to bundled Gradle dependencies

- Groovy has been updated to https://groovy-lang.org/releasenotes/groovy-3.0.html[Groovy 3.0.8].
- Kotlin has been updated to https://github.com/JetBrains/kotlin/releases/tag/v1.5.21[Kotlin 1.5.21].

==== Updates to default tool integration versions

- PMD has been updated to https://github.com/pmd/pmd/releases/tag/pmd_releases%2F6.36.0[PMD 6.36.0].

=== Deprecations

[[java_lamdba_action]]
==== Using Java lambdas as task actions

When using a Java lambda to implement a task action, Gradle cannot track the implementation and the task will never be up-to-date of from the build cache.
Since it is easy to add such a task action, using task actions implemented by Java lambdas is now deprecated.
See <<validation_problems.adoc#implementation_unknown,Validation problems>> for more details how to fix the issue.

[[equals_up_to_date_deprecation]]
==== Relying on equals for up-to-date checks is deprecated

When a task input is annotated with `@Input` and is not a type Gradle understand directly (like `String`), then Gradle uses the serialized form of the input for up-to-date checks and the build cache key.
Historically, Gradle also loads the serialized value from the last execution and then uses `equals()` to compare it to the current value for up-to-date checks.
Doing so is error prone, doesn't work with the build cache and has a performance impact, therefore it has been deprecated.
Instead of using at `@Input` on a type Gradle doesn't understand directly, use `@Nested` and annotate the properties of the type accordingly.

[[changes_7.1]]
== Upgrading from 7.0 and earlier

=== Potential breaking changes

==== Updates to default tool integration versions

- JaCoCo has been updated to http://www.jacoco.org/jacoco/trunk/doc/changes.html[0.8.7].

==== The `org.gradle.util` package is now a public API

Officially, the `org.gradle.util` package is not part of the public API.
But, because this package name doesn't contain the word `internal`, many Gradle plugins already consider as one.
Gradle 7.1 addresses the situation and marks the package as public.
The classes that were unintentionally exposed are either deprecated or removed, depending on their external usage.

===== The following classes are now officially recognized as public API:
- `GradleVersion`
- `Path`
- `Configurable`

===== The following classes have known usages in external plugins and are now deprecated and set for removal in Gradle 8.0:

- `VersionNumber`
- `TextUtil`
- `WrapUtil`
- `RelativePathUtil`
- `DistributionLocator`
- `SingleMessageLogger`
- `ConfigureUtil`

`ConfigureUtil` is being removed without a replacement. Plugins can avoid the need for using `ConfigureUtil` by following link:{javadocPath}/org/gradle/util/ConfigureUtil.html[our example].

===== The following classes have only internal usages and were moved from `org.gradle.util` to the `org.gradle.util.internal` package:

- `Resources`
- `RedirectStdOutAndErr`
- `Swapper`
- `StdInSwapper`
- `IncubationLogger`
- `RedirectStdIn`
- `MultithreadedTestRule`
- `DisconnectableInputStream`
- `BulkReadInputStream`
- `MockExecutor`
- `FailsWithMessage`
- `FailsWithMessageExtension`
- `TreeVisitor`
- `AntUtil`
- `JarUtil`

===== The last set of classes have no external or internal usages and therefore were deleted:

- `DiffUtil`
- `NoopChangeListener`
- `EnumWithClassBody`
- `AlwaysTrue`
- `ReflectionEqualsMatcher`
- `DynamicDelegate`
- `IncubationLogger`
- `NoOpChangeListener`
- `DeferredUtil`
- `ChangeListener`

==== The return type of source set extensions have changed

The following source sets are contributed via an extension with a custom type:

- `groovy`: link:{groovyDslPath}/org.gradle.api.tasks.GroovySourceDirectorySet.html[GroovySourceDirectorySet]
- `antlr`: link:{groovyDslPath}/org.gradle.api.plugins.antlr.AntlrSourceDirectorySet.html[AntlrSourceDirectorySet]
- `scala`: link:{groovyDslPath}/org.gradle.api.tasks.ScalaSourceDirectorySet.html[ScalaSourceDirectorySet]

The 'idiomatic' DSL declaration is backward compatible:

```groovy
sourceSets {
    main {
        groovy {
            // ...
        }
    }
}
```

However, the return type of the groovy block has changed to the extension type. This means that the following snippet no longer works in Gradle 7.1:

```groovy
 sourceSets {
     main {
         GroovySourceSet sourceSet = groovy {
             // ...
         }
     }
 }
```

==== Start scripts require bash shell

The command used to start Gradle, the Gradle wrapper as well as the scripts generated by the `application` plugin
now require `bash` shell.

=== Deprecations

[[convention_mapping]]
==== Using convention mapping with properties with type Provider is deprecated
Convention mapping is an internal feature that is been replaced by the <<lazy_configuration#lazy_configuration,Provider API>>.
When mixing convention mapping with the Provider API, unexpected behavior can occur.
Gradle emits a deprecation warning when a property in a task, extension or other domain object uses convention mapping with the Provider API.

To fix this, the plugin that configures the convention mapping for the task, extension or domain object needs to be changed to use the Provider API only.

[[jacoco_merge]]
==== JacocoMerge task type is deprecated

The `JacocoMerge` task was used for merging coverage reports from different subprojects into a single report.
The same functionality is also available on the `JacocoReport` task.
Because of the duplication, `JacocoMerge` is now deprecated and scheduled for removal in Gradle 8.0.

[[configuring_custom_build_layout]]
==== Setting custom build layout

Command line options:

* `-c`, `--settings-file` for specifying a custom settings file location
* `-b`, `--build-file` for specifying a custom build file location

have been deprecated.

Setting custom build file using
link:{groovyDslPath}/org.gradle.api.tasks.GradleBuild.html#org.gradle.api.tasks.GradleBuild:buildFile[buildFile]
property in link:{groovyDslPath}/org.gradle.api.tasks.GradleBuild.html[GradleBuild] task has been deprecated.

Please use the link:{groovyDslPath}/org.gradle.api.tasks.GradleBuild.html#org.gradle.api.tasks.GradleBuild:dir[dir]
property instead to specify the root of the nested build.
Alternatively, consider using one of the recommended alternatives for
link:{groovyDslPath}/org.gradle.api.tasks.GradleBuild.html[GradleBuild] task as suggested in
<<authoring_maintainable_build_scripts#sec:avoiding_use_of_gradlebuild, Avoid using the GradleBuild task type>> section.

Setting custom build layout using
link:{javadocPath}/org/gradle/StartParameter.html[StartParameter] methods
link:{javadocPath}/org/gradle/StartParameter.html#setBuildFile-java.io.File-[setBuildFile(File)]
and
link:{javadocPath}/org/gradle/StartParameter.html#setSettingsFile-java.io.File-[setSettingsFile(File)]
as well as the counterpart getters
link:{javadocPath}/org/gradle/StartParameter.html#getBuildFile--[getBuildFile()]
and
link:{javadocPath}/org/gradle/StartParameter.html#getSettingsFile--[getSettingsFile()]
have been deprecated.

Please use standard locations for settings and build files:

* settings file in the root of the build
* build file in the root of each subproject

For the use case where custom settings or build files are used to model different behavior (similar to Maven profiles),
consider using <<build_environment#sec:gradle_system_properties, system properties>> with conditional logic.
For example, given a piece of code in either settings or build file:
```
if (System.getProperty("profile") == "custom") {
    println("custom profile")
} else {
    println("default profile")
}
```
You can pass the `profile` system property to Gradle using `gradle -Dprofile=custom` to execute the code in the `custom` profile branch.

[[dependency_substitutions_with]]
==== Substitution.with replaced with Substitution.using

<<resolution_rules#sec:dependency_substitution_rules, Dependency substitutions>> using `with` method have been deprecated
and are replaced with `using` method that also allows chaining.
For example, a dependency substitution rule `substitute(project(':a')).with(project(':b'))` should be replaced with
`substitute(project(':a')).using(project(':b'))`.
With chaining you can, for example, add a reason for a substitution like this:
`substitute(project(':a')).using(project(':b')).because("a reason")`.

[[java_exec_properties]]
==== Properties deprecated in JavaExec task

* The link:{groovyDslPath}/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:main[main] getters and setters
in link:{groovyDslPath}/org.gradle.api.tasks.JavaExec.html[JavaExec] task have been deprecated.
Use the link:{groovyDslPath}/org.gradle.api.tasks.JavaExec.html#org.gradle.api.tasks.JavaExec:mainClass[mainClass] property instead.

[[compile_task_wiring]]
==== Deprecated properties in `compile` task

* The link:{groovyDslPath}/org.gradle.api.tasks.compile.JavaCompile.html#org.gradle.api.tasks.compile.JavaCompile:destinationDir[JavaCompile.destinationDir]
property has been deprecated.
Use the link:{groovyDslPath}/org.gradle.api.tasks.compile.JavaCompile.html#org.gradle.api.tasks.compile.JavaCompile:destinationDirectory[JavaCompile.destinationDirectory]
property instead.
* The link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html#org.gradle.api.tasks.compile.GroovyCompile:destinationDir[GroovyCompile.destinationDir]
property has been deprecated.
Use the link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html#org.gradle.api.tasks.compile.GroovyCompile:destinationDirectory[GroovyCompile.destinationDirectory]
property instead.
* The link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html#org.gradle.api.tasks.scala.ScalaCompile:destinationDir[ScalaCompile.destinationDir]
property has been deprecated.
Use the link:{groovyDslPath}/org.gradle.api.tasks.scala.ScalaCompile.html#org.gradle.api.tasks.scala.ScalaCompile:destinationDirectory[ScalaCompile.destinationDirectory]
property instead.

[[non_hierarchical_project_structures]]
==== Non-hierarchical project layouts

Gradle 7.1 deprecated project layouts where subprojects were located outside of the project root.
However, based on link:https://github.com/gradle/gradle/issues/18644[community feedback] we decided to roll back in Gradle 7.4 and removed the deprecation.
As a consequence, the link:{groovyDslPath}/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeFlat(java.lang.String&#91;&#93;)[Settings.includeFlat()] method is deprecated in Gradle 7.1, 7.2, and 7.3 only.

[[upload_task_deprecation]]
==== Deprecated `Upload` task

Gradle used to have two ways of publishing artifacts.
Now, the situation has been cleared and all build should use the `maven-publish` plugin.
The last remaining artifact of the old way of publishing is the `Upload` task that has been deprecated and scheduled for removal in Gradle 8.0.
Existing clients should migrate to the <<publishing_maven.adoc#publishing_maven,`maven-publish` plugin>>.

[[all_convention_deprecation]]
==== Deprecated conventions
The concept of conventions is outdated and superseded by extensions. To reflect this in the Gradle API, the following elements are now deprecated:

- link:{javadocPath}/org/gradle/api/Project.html#getConvention--[Project.html#getConvention()]
- link:{javadocPath}/org/gradle/api/internal/HasConvention.html[HasConvention]

The internal usages of conventions have been also cleaned up (see the deprecated items below).

Plugin authors migrate to extensions if they replicate the changes we've done internally. Here are some examples:

- Migrate plugin configuration: link:https://github.com/gradle/gradle/pull/16900/files#diff-ac53d4f39698b83e30b93855fe6a725ffd96d5ed9df156d4f9dfd32bdc7946e7[gradle/gradle#16900].
- Migrate custom source sets: link:https://github.com/gradle/gradle/pull/17149/files#diff-e159587e2f9aec398fa795b1d8b344f1593cb631e15e04893d31cdc9465f9781[gradle/gradle#17149].

[[base_convention_deprecation]]
==== Deprecated `base` plugin conventions

The convention properties contributed by the `base` plugin have been deprecated and scheduled for removal in Gradle 8.0.
The conventions are replaced by the the `base { }` configuration block backed by link:{groovyDslPath}/org.gradle.api.plugins.BasePluginExtension.html[BasePluginExtension].

The old convention object defines the `distsDirName`, `libsDirName` and `archivesBaseName` properties with simple getter and setter methods.
Those methods are available in the extension only to maintain backwards compatibility.
Build scripts should solely use the properties of type `Property`:
```
base {
    archivesName = 'customBase'
    distsDirectory = layout.buildDirectory.dir('custom-dist')
    libsDirectory = layout.buildDirectory.dir('custom-libs')
}
```

[[application_convention_deprecation]]
==== Deprecated `ApplicationPluginConvention`

link:{javadocPath}/org/gradle/api/plugins/ApplicationPluginConvention.html[ApplicationPluginConvention] was already listed as deprecated in the <<application_plugin.adoc#sec:application_convention_properties, documentation>>.
Now, it is officially annotated as deprecated and scheduled for removal in Gradle 8.0.

[[java_convention_deprecation]]
==== Deprecated `java` plugin conventions

The convention properties contributed by the `java` plugin have been deprecated and scheduled for removal in Gradle 8.0.
They are replaced by the the properties of link:{groovyDslPath}/org.gradle.api.plugins.JavaPluginExtension.html[JavaPluginExtension] which can be configured in the `java {}` block.

[[plugin_configuration_consumption]]
==== Deprecated consumption of internal plugin configurations

Some of the core Gradle plugins declare configurations that are used by the plugin itself and are not meant to be
published or consumed by another subproject directly. Gradle did not explicitly prohobit this.
Gradle 7.1 deprecates consumption of those configurations and this will become an error in Gradle 8.0.

The following plugin configurations have been deprecated for consumption:

[cols="1,1"]
|===
| plugin | configurations deprecated for consumption

| `codenarc`
| `codenarc`

| `pmd`
| `pmd`

| `checkstyle`
| `checkstyle`

| `antlr`
| `antlr`

| `jacoco`
| `jacocoAnt`, `jacocoAgent`

| `scala`
| `zinc`

| `war`
| `providedCompile`, `providedRuntime`
|===

If your use case needs to consume any of the above mentioned configurations in another project, please create a separate consumable
configuration that extends from the internal ones. For example:
```
plugins {
    id("codenarc")
}
configurations {
    codenarc {
        // because currently this is consumable until Gradle 8.0 and can clash with the configuration below depending on the attributes set
        canBeConsumed = false
    }
    codenarcConsumable {
        extendsFrom(codenarc)
        canBeConsumed = true
        canBeResolved = false
        // the attributes below make this configuration consumable by a `java-library` project using `implementation` configuration
        attributes {
            attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
            attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.LIBRARY))
            attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements, LibraryElements.JAR))
            attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling, Bundling.EXTERNAL))
            attribute(TargetJvmEnvironment.TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(TargetJvmEnvironment, TargetJvmEnvironment.STANDARD_JVM));
        }
    }
}
```

[[project_report_convention_deprecation]]
==== Deprecated `project-report` plugin conventions

link:{groovyDslPath}/org.gradle.api.plugins.ProjectReportsPluginConvention.html[ProjectReportsPluginConvention] is now deprecated and scheduled for removal in Gradle 8.0. Clients should configure the project report tasks directly. Also, link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(...).configureEach(...)] can be used to configure each task of the same type (`HtmlDependencyReportTask` for example).

[[war_convention_deprecation]]
==== Deprecated `war` plugin conventions

link:{javadocPath}/org/gradle/api/plugins/WarPluginConvention.html[WarPluginConvention] is now deprecated and scheduled for removal in Gradle 8.0. Clients should configure the `war` task  directly. Also, link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(War.class).configureEach(...)] can be used to configure each task of type `War`.

[[ear_convention_deprecation]]
==== Deprecated `ear` plugin conventions

link:{javadocPath}/org/gradle/plugins/ear/EarPluginConvention.html[EarPluginConvention] is now deprecated and scheduled for removal in Gradle 8.0. Clients should configure the `ear` task directly. Also, link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(Ear.class).configureEach(...)] can be used to configure each task of type `Ear`.

[[custom_source_set_deprecation]]
==== Deprecated custom source set interfaces
The following source set interfaces are now deprecated and scheduled for removal in Gradle 8.0:

- link:{javadocPath}/org/gradle/api/tasks/GroovySourceSet.html[GroovySourceSet]
- link:{javadocPath}/org/gradle/api/plugins/antlr/AntlrSourceVirtualDirectory.html[AntlrSourceVirtualDirectory]
- link:{javadocPath}/org/gradle/api/tasks/ScalaSourceSet.html[ScalaSourceSet]

Clients should configure the sources with their plugin-specific configuration:

- `groovy`: link:{javadocPath}/org/gradle/api/tasks/GroovySourceDirectorySet.html[GroovySourceDirectorySet]
- `antlr`: link:{javadocPath}/org/gradle/api/plugins/antlr/AntlrSourceDirectorySet.html[AntlrSourceDirectorySet]
- `scala`: link:{javadocPath}/org/gradle/api/tasks/ScalaSourceDirectorySet.html[ScalaSourceDirectorySet]

For example, here's how you configure the groovy sources from a plugin:

```java
GroovySourceDirectorySet groovySources = sourceSet.getExtensions().getByType(GroovySourceDirectorySet.class);
groovySources.setSrcDirs(Arrays.asList("sources/groovy"));
```

[[old_artifact_transforms_api]]
==== Registering artifact transforms extending `ArtifactTransform`

When Gradle first introduced artifact transforms, it used the base class `ArtifactTransform` for implementing them.
Gradle 5.3 introduced the interface `TransformAction` for implementing artifact transforms, replacing the previous class `ArtifactTransform` and addressing various shortcomings.
Using the registration method link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyHandler.html#org.gradle.api.artifacts.dsl.DependencyHandler:registerTransform(org.gradle.api.Action)[DependencyHandler.registerTransform(Action)] for `ArtifactTransform` has been deprecated.
Migrate your artifact transform to use `TransformAction` and use link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyHandler.html#org.gradle.api.artifacts.dsl.DependencyHandler:registerTransform(java.lang.Class,%20org.gradle.api.Action)[DependencyHandler.registerTransform(Class, Action)] instead.
See the <<artifact_transforms#sec:abm_artifact_transforms,user manual>> for more information on implementing `TransformAction`.
