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

[[upgrading_version_5]]
= Upgrading your build from Gradle 5.x to 6.0

This chapter provides the information you need to migrate your Gradle 5.x builds to Gradle 6.0.
For migrating from Gradle 4.x, complete the <<upgrading_version_4.adoc#upgrading_version_4, 4.x to 5.0 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 can 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 6.0` to update the project to 6.0.
. Try to run the project and debug any errors using the <<troubleshooting.adoc#troubleshooting, Troubleshooting Guide>>.

[[changes_6.0]]
== Upgrading from 5.6 and earlier

=== Deprecations

==== Dependencies should no longer be declared using the `compile` and `runtime` configurations

The usage of the `compile` and `runtime` configurations in the Java ecosystem plugins has been discouraged since https://docs.gradle.org/3.4/release-notes.html#the-java-library-plugin[Gradle 3.4].

These configurations are used for compiling and running code from the `main` source set.
Other sources sets create similar configurations (e.g. `testCompile` and `testRuntime` for the `test` source set), should not be used either.
The `implementation`, `api`, `compileOnly` and `runtimeOnly` configurations should be used to declare dependencies and the `compileClasspath` and `runtimeClasspath` configurations to resolve dependencies.
See <<java_library_plugin.adoc#sec:java_library_configurations_graph, the relationship of these configurations>>.

==== Legacy publication system is deprecated and replaced with the `*-publish` plugins

The `uploadArchives` task and the `maven` plugin are deprecated.

Users should migrate to the <<publishing_setup.adoc#publishing_components,publishing system>> of Gradle by using either the <<publishing_maven.adoc#publishing_maven,`maven-publish`>> or <<publishing_ivy.adoc#publishing_ivy,`ivy-publish`>> plugins.
These plugins have been stable since Gradle 4.8.

The publishing system is also the only way to ensure the publication of <<publishing_gradle_module_metadata.adoc#sec:understanding-gradle-module-md,Gradle Module Metadata>>.

==== Problems with tasks emit deprecation warnings

When Gradle detects problems with task definitions (such as incorrectly defined inputs or outputs) it will show the following message on the console:

```
Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org/6.0/userguide/command_line_interface.html#sec:command_line_warnings
```

The deprecation warnings show up in https://scans.gradle.com/s/txrptciitl2ha/deprecations[build scans] for every build, regardless of the command-line switches used.

When the build is executed with `--warning-mode all`, the individual warnings will be shown:

```
> Task :myTask
Property 'inputDirectory' is declared without normalization specified. Properties of cacheable work must declare their normalization via @PathSensitive, @Classpath or @CompileClasspath. Defaulting to PathSensitivity.ABSOLUTE. This behavior is scheduled to be removed in Gradle 7.0.
Property 'outputFile' is not annotated with an input or output annotation. This behavior is scheduled to be removed in Gradle 7.0.
```

If you own the code of the tasks in question, you can fix them by <<incremental_build.adoc#sec:task_input_validation, following the suggestions>>.
You can also use `--stacktrace` to see where in the code each warning originates from.

Otherwise, you'll need to report the problems to the maintainer of the relevant task or plugin.

==== Old API for incremental tasks, `IncrementalTaskInputs`, has been deprecated

In Gradle 5.4 we introduced a new API for implementing <<custom_tasks.adoc#incremental_tasks,incremental tasks>>: link:{groovyDslPath}/org.gradle.work.InputChanges.html[InputChanges]. The old API based on `IncrementalTaskInputs` has been deprecated.

==== Forced dependencies

Forcing dependency versions using `force = true` on a first-level dependency has been deprecated.

Force has both a semantic and ordering issue which can be avoided by using a <<dependency_versions.adoc#sec:rich-version-constraints, strict version constraint>>.

==== Search upwards related APIs in `StartParameter` have been deprecated

In Gradle 5.0, we removed the `--no-search-upward` CLI parameter.

The related APIs in `StartParameter` (like `isSearchUpwards()`) are now deprecated.

==== APIs `BuildListener.buildStarted` and `Gradle.buildStarted` have been deprecated

These methods currently do not work as expected since the callbacks will never be called after the build has started.

The methods are being deprecated to avoid confusion.

==== Implicit duplicate strategy for `Copy` or archive tasks has been deprecated

Archive tasks `Tar` and `Zip` by default allow multiple entries for the same path to exist in the created archive.
This can cause https://github.com/gradle/gradle/issues/9990["grossly invalid zip files" that can trigger zip bomb detection].

To prevent this from happening accidentally, encountering duplicates while creating an archive now produces a deprecation message and will fail the build starting with Gradle 7.0.

`Copy` tasks also happily copy multiple sources with the same relative path to the destination directory.
This behavior has also been deprecated.

If you want to allow duplicates, you can specify that explicitly:
```
task archive(type: Zip) {
    duplicatesStrategy = DuplicatesStrategy.INCLUDE // allow duplicates
    ...
}
```

==== Executing Gradle without a settings file has been deprecated

A Gradle build is defined by a `settings.gradle[.kts]` file in the current or parent directory.
Without a settings file, a Gradle build is undefined and will emit a deprecation warning.

In Gradle 7.0, Gradle will only allow you to invoke the `init` task or diagnostic command line flags, such as `--version`, with undefined builds.

==== Calling `Project.afterEvaluate` on an evaluated project has been deprecated

Once a project is evaluated, Gradle ignores all configuration passed to `Project#afterEvaluate` and emits a deprecation warning.
This scenario will become an error in Gradle 7.0.

==== Deprecated plugins

The following bundled plugins were never announced and will be removed in the next major release of Gradle:

- `org.gradle.coffeescript-base`
- `org.gradle.envjs`
- `org.gradle.javascript-base`
- `org.gradle.jshint`
- `org.gradle.rhino`

Some of these plugins may have replacements on the https://plugins.gradle.org/[Plugin Portal].

=== Potential breaking changes

==== Android Gradle Plugin 3.3 and earlier is no longer supported

Gradle 6.0 supports Android Gradle Plugin versions 3.4 and later.

==== Build scan plugin 2.x is no longer supported

For Gradle 6, usage of the build scan plugin must be replaced with the Develocity plugin.
This also requires changing how the plugin is applied.
Please see https://gradle.com/help/gradle-6-build-scan-plugin for more information.

==== Updates to bundled Gradle dependencies

- Groovy has been updated to http://groovy-lang.org/changelogs/changelog-2.5.8.html[Groovy 2.5.8].
- Kotlin has been updated to https://blog.jetbrains.com/kotlin/2019/08/kotlin-1-3-50-released/[Kotlin 1.3.50].
- Ant has been updated to https://archive.apache.org/dist/ant/RELEASE-NOTES-1.10.7.html[Ant 1.10.7].

==== Updates to default integration versions

- Checkstyle has been updated to https://checkstyle.org/releasenotes.html#Release_8.24[Checkstyle 8.24].
- CodeNarc has been updated to https://github.com/CodeNarc/CodeNarc/blob/master/CHANGELOG.md#version-14---may-2019[CodeNarc 1.4].
- PMD has been updated to https://pmd.github.io/latest/pmd_release_notes.html#28-july-2019---6170[PMD 6.17.0].
- JaCoCo has been updated to http://www.jacoco.org/jacoco/trunk/doc/changes.html[0.8.5]. Contributed by link:https://github.com/Godin[Evgeny Mandrikov]

==== Changes to build and task names in composite builds

Previously, Gradle used the name of the root project as the build name for an included build.
Now, the name of the build's root directory is used and the root project name is not considered if different.
A different name for the build can be specified if the build is being included via a settings file.

```kotlin
includeBuild("some-other-build") {
    name = "another-name"
}
```

The previous behavior was problematic as it caused different names to be used at different times during the build.

==== buildSrc is now reserved as a project and subproject build name

Previously, Gradle did not prevent using the name "buildSrc" for a subproject of a multi-project build or as the name of an included build.
Now, this is not allowed.
The name "buildSrc" is now reserved for the conventional buildSrc project that builds extra build logic.

Typical use of buildSrc is unaffected by this change.
You will only be affected if your settings file specifies `include("buildSrc")` or `includeBuild("buildSrc")`.

==== Scala Zinc compiler

The Zinc compiler has been upgraded to version 1.3.0. Gradle no longer supports building for Scala 2.9.

The minimum Zinc compiler supported by Gradle is 1.2.0 and the maximum tested version is 1.3.0.

To make it easier to select the version of the Zinc compiler, you can now configure a `zincVersion` property:
```
scala {
    zincVersion = "1.2.1"
}
```

Please remove any explicit dependencies you've added to the `zinc` configuration and use this property instead.
If you try to use the `com.typesafe.zinc:zinc` dependency, Gradle will switch to the new Zinc implementation.

==== Changes to Build Cache

==== Local build cache is always a directory cache

In the past, it was possible to use any build cache implementation as the `local` cache.
This is no longer allowed as the local cache must always be a `DirectoryBuildCache`.

Calls to `BuildCacheConfiguration.local(Class)` with anything other than `DirectoryBuildCache` as the type will fail the build.
Calling these methods with the `DirectoryBuildCache` type will produce a deprecation warning.

Use `getLocal()` and `local(Action)` instead.

==== Failing to pack or unpack cached results will now fail the build

In the past, when Gradle encountered a problem while packing the results of a cached task, Gradle would ignore the problem and continue running the build.

When encountering a corrupt cached artifact, Gradle would remove whatever was already unpacked and re-execute the task to make sure the build had a chance to succeed.

While this behavior was intended to make a build successful, this had the adverse effect of hiding problems and led to reduced cache performance.

In Gradle 6.0, both pack and unpack errors will cause the build to fail, so that these problems will be surfaced more easily.

==== buildSrc projects automatically use build cache configuration

Previously, in order to use the build cache for the buildSrc build you needed to duplicate your build cache config in the buildSrc build.
Now, it automatically uses the build cache configuration defined by the top level settings script.

==== Changes to Dependency Management

==== Gradle Module Metadata is always published

Officially introduced in Gradle 5.3, https://blog.gradle.org/gradle-metadata-1.0[Gradle Module Metadata] was created to solve many of the problems that have plagued dependency management for years, in particular, but not exclusively, in the Java ecosystem.

With Gradle 6.0, Gradle Module Metadata is enabled by default.

This means, if you are publishing libraries with Gradle and using the <<publishing_maven.adoc#publishing_maven,maven-publish>> or <<publishing_ivy.adoc#publishing_ivy,ivy-publish>> plugin, the Gradle Module Metadata file is always published *in addition* to traditional metadata.

The traditional metadata file will contain a marker so that Gradle knows that there is additional metadata to consume.

==== Gradle Module Metadata has stricter validation

The following rules are verified when publishing Gradle Module Metadata:

* Variant names must be unique,
* Each variant must have at least <<variant_attributes.adoc#variant-attributes,one attribute>>,
* Two variants cannot have the <<variant_aware_resolution.adoc#sec:understanding-variant-selection,exact same attributes and capabilities>>,
* If there are dependencies, at least one, across all variants, must carry <<dependency_versions.adoc#sec:rich-version-constraints,version information>>.

These are documented in the link:https://github.com/gradle/gradle/blob/master/platforms/documentation/docs/src/docs/design/gradle-module-metadata-latest-specification.md[specification] as well.

==== Maven or Ivy repositories are no longer queried for artifacts without metadata by default

If Gradle fails to locate the metadata file (`.pom` or `ivy.xml`) of a module in a repository defined in the `repositories { }` section, it now assumes that the module does not exist in that repository.

For dynamic versions, the `maven-metadata.xml` for the corresponding module needs to be present in a Maven repository.

Previously, Gradle would also look for a default artifact (`.jar`).
This behavior often caused a large number of unnecessary requests when using multiple repositories that slowed builds down.

You can opt into the old behavior for selected repositories by adding the `artifact()` <<supported_metadata_formats.adoc#sec:supported-metadata-sources,metadata source>>.

==== Changing the pom `packaging` property no longer changes the artifact extension

Previously, if the pom packaging was not _jar_, _ejb_, _bundle_ or _maven-plugin_, the extension of the main artifact published to a Maven repository was changed during publishing to match the pom packaging.

This behavior led to broken Gradle Module Metadata and was difficult to understand due to handling of different packaging types.

Build authors can change the artifact name when the artifact is created to obtain the same result as before — e.g. by setting `jar.archiveExtension.set(pomPackaging)` explicitly.

==== An `ivy.xml` published for Java libraries contains more information

A number of fixes were made to produce more correct `ivy.xml` metadata in the `ivy-publish` plugin.

As a consequence, the internal structure of the `ivy.xml` file has changed. The `runtime` configuration now contains more information, which corresponds to the _runtimeElements_ variant of a Java library.
The `default` configuration should yield the same result as before.

In general, users are advised to migrate from `ivy.xml` to the new Gradle Module Metadata format.

==== Changes to Plugins and Build scripts

==== Classes from `buildSrc` are no longer visible to settings scripts

Previously, the buildSrc project was built before applying the project's settings script and its classes were visible within the script.
Now, buildSrc is built after the settings script and its classes are not visible to it.
The buildSrc classes remain visible to project build scripts and script plugins.

Custom logic can be used from a settings script by <<tutorial_using_tasks.adoc#sec:build_script_external_dependencies, declaring external dependencies>>.

==== The `pluginManagement` block in settings scripts is now isolated

Previously, any `pluginManagement {}` blocks inside a settings script were executed during the normal execution of the script.

Now, they are executed earlier in a similar manner to `buildscript {}` or `plugins {}`.
This means that code inside such a block cannot reference anything declared elsewhere in the script.

This change has been made so that `pluginManagement` configuration can also be applied when resolving plugins for the settings script itself.

==== Plugins and classes loaded in settings scripts are visible to project scripts and `buildSrc`

Previously, any classes added to the a settings script by using `buildscript {}` were not visible outside of the script.
Now, they are visible to all of the project build scripts.

They are also visible to the `buildSrc` build script and its settings script.

This change has been made so that plugins applied to the settings script can contribute logic to the entire build.

==== Plugin validation changes

- The `validateTaskProperties` task is now deprecated, use `validatePlugins` instead.
  The new name better reflects the fact that it also validates artifact transform parameters and other non-property definitions.
- The `ValidateTaskProperties` type is replaced by `ValidatePlugins`.
- The `setClasses()` method is now removed. Use `getClasses().setFrom()` instead.
- The `setClasspath()` method is also removed. use `getClasspath().setFrom()` instead.
- The link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidatePlugins.html#getFailOnWarning--[failOnWarning] option is now enabled by default.
- The following task validation errors now fail the build at runtime and are promoted to errors for link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidatePlugins.html[ValidatePlugins]:
  * A task property is annotated with a property annotation not allowed for tasks, like `@InputArtifact`.

==== Changes to Kotlin DSL

==== Using the `embedded-kotlin` plugin now requires a repository

Just like when using the `kotlin-dsl` plugin, it is now required to declare a repository where Kotlin dependencies can be found if you apply the `embedded-kotlin` plugin.

```kotlin
plugins {
    `embedded-kotlin`
}

repositories {
    mavenCentral()
}
```

==== Kotlin DSL IDE support now requires Kotlin IntelliJ Plugin >= 1.3.50

With Kotlin IntelliJ plugin versions prior to 1.3.50, Kotlin DSL scripts will be wrongly highlighted when the _Gradle JVM_ is set to a version different from the one in _Project SDK_.
Simply upgrade your IDE plugin to a version >= 1.3.50 to restore the correct Kotlin DSL script highlighting behavior.

==== Kotlin DSL script base types no longer extend `Project`, `Settings` or `Gradle`

In previous versions, Kotlin DSL scripts were compiled to classes that implemented one of the three core Gradle configuration interfaces in order to implicitly expose their APIs to scripts. `org.gradle.api.Project` for project scripts, `org.gradle.api.initialization.Settings` for settings scripts and `org.gradle.api.invocation.Gradle` for init scripts.

Having the script instance implement the core Gradle interface of the model object it was supposed to configure was convenient because it made the model object API immediately available to the body of the script but it was also a lie that could cause all sorts of trouble whenever the script itself was used in place of the model object, a project script **was not** a proper `Project` instance just because it implemented the core `Project` interface and the same was true for settings and init scripts.

In 6.0 all Kotlin DSL scripts are compiled to classes that implement the newly introduced `org.gradle.kotlin.dsl.KotlinScript` interface and the corresponding model objects are now available as _implicit receivers_ in the body of the scripts. In other words, a project script behaves as if the body of the script is enclosed within a `with(project) { ... }` block, a settings script as if the body of the script is enclosed within a `with(settings) { ... }` block and an init script as if the body of the script is enclosed within a `with(gradle) { ... }` block. This implies the corresponding model object is also available as a property in the body of the script, the `project` property for project scripts, the `settings` property for settings scripts and the `gradle` property for init scripts.

As part of the change, the `SettingsScriptApi` interface is no longer implemented by settings scripts and the `InitScriptApi` interface is no longer implemented by init scripts. They should be replaced with the corresponding model object interfaces, `Settings` and `Gradle`.

==== Miscellaneous

==== Javadoc and Groovydoc don't include timestamps by default

Timestamps in the generated documentation have very limited practical use, however they make it impossible to have repeatable documentation builds.
Therefore, the `Javadoc` and `Groovydoc` tasks are now configured to not include timestamps by default any more.

==== User provided 'config_loc' properties are ignored by Checkstyle

Gradle always uses `configDirectory` as the value for 'config_loc' when running Checkstyle.

==== New Tooling API progress event

In Gradle 6.0, we introduced a new progress event (link:{javadocPath}/org/gradle/tooling/events/test/TestOutputEvent.html[org.gradle.tooling.events.test.TestOutputEvent]) to expose the output of test execution.
This new event breaks the convention of having a `StartEvent`-`FinishEvent` pair to express progress.
`TaskOutputEvent` is a simple `ProgressEvent`.

==== Changes to the task container behavior

The following deprecated methods on the task container now result in errors:

- `TaskContainer.add()`
- `TaskContainer.addAll()`
- `TaskContainer.remove()`
- `TaskContainer.removeAll()`
- `TaskContainer.retainAll()`
- `TaskContainer.clear()`
- `TaskContainer.iterator().remove()`

Additionally, the following deprecated functionality now results in an error:

- Replacing a task that has already been realized.
- Replacing a registered (unrealized) task with an incompatible type. A compatible type is the same type or a sub-type of the registered type.
- Replacing a task that has never been registered.

==== Replaced and Removed APIs

==== Methods on `DefaultTask` and `ProjectLayout` replaced with `ObjectFactory`

Use `ObjectFactory.fileProperty()` instead of the following methods that are now removed:

- `DefaultTask.newInputFile()`
- `DefaultTask.newOutputFile()`
- `ProjectLayout.fileProperty()`

Use `ObjectFactory.directoryProperty()` instead of the following methods that are now removed:

- `DefaultTask.newInputDirectory()`
- `DefaultTask.newOutputDirectory()`
- `ProjectLayout.directoryProperty()`

==== Annotation `@Nullable` has been removed

The `org.gradle.api.Nullable` annotation type has been removed. Use `javax.annotation.Nullable` from JSR-305 instead.

==== The FindBugs plugin has been removed

The deprecated FindBugs plugin has been removed.
As an alternative, you can use the link:https://plugins.gradle.org/plugin/com.github.spotbugs[SpotBugs plugin] from the link:https://plugins.gradle.org/search?term=spotbugs[Gradle Plugin Portal].

==== The JDepend plugin has been removed

The deprecated JDepend plugin has been removed.
There are a number of community-provided plugins for code and architecture analysis available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The OSGI plugin has been removed

The deprecated OSGI plugin has been removed.
There are a number of community-provided OSGI plugins available on the link:https://plugins.gradle.org/search?term=osgi[Gradle Plugin Portal].

==== The announce and build-announcements plugins have been removed

The deprecated announce and build-announcements plugins have been removed.
There are a number of community-provided plugins for sending out notifications available on the link:https://plugins.gradle.org[Gradle Plugin Portal].

==== The Compare Gradle Builds plugin has been removed

The deprecated Compare Gradle Builds plugin has been removed.
Please use https://scans.gradle.com/[build scans] for build analysis and comparison.

==== The Play plugins have been removed

The deprecated Play plugin has been removed.
An external replacement, the link:https://gradle.github.io/playframework[Play Framework plugin], is available from the plugin portal.

==== Method `AbstractCompile.compile()` method has been removed

The abstract method `compile()` is no longer declared by `AbstractCompile`.

Tasks extending `AbstractCompile` can implement their own `@TaskAction` method with the name of their choosing.

They are also free to add a method annotated with `@TaskAction` using an `InputChanges` parameter without having to implement a parameter-less one as well.

==== Other Deprecated Behaviors and APIs

* The `org.gradle.util.internal.GUtil.savePropertiesNoDateComment` has been removed. There is no public replacement for this internal method.
* The deprecated class `org.gradle.api.tasks.compile.CompilerArgumentProvider` has been removed.
  Use link:{javadocPath}/org/gradle/process/CommandLineArgumentProvider.html[org.gradle.process.CommandLineArgumentProvider] instead.
* The deprecated class `org.gradle.api.ConventionProperty` has been removed.
  Use link:{javadocPath}/org/gradle/api/provider/Provider.html[Providers] instead of convention properties.
* The deprecated class `org.gradle.reporting.DurationFormatter` has been removed.
* The bridge method `org.gradle.api.tasks.TaskInputs.property(String name, @Nullable Object value)` returning `TaskInputs` has been removed.
  A plugin using the method must be compiled with Gradle 4.3 to work on Gradle 6.0.
* The following setters have been removed from `JacocoReportBase`:
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:executionData[executionData] - use `getExecutionData().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:sourceDirectories[sourceDirectories] - use `getSourceDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:classDirectories[classDirectories] - use `getClassDirectories().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalClassDirs[additionalClassDirs] - use `getAdditionalClassDirs().setFrom()` instead.
** link:{groovyDslPath}/org.gradle.testing.jacoco.tasks.JacocoReport.html#org.gradle.testing.jacoco.tasks.JacocoReport:additionalSourceDirs[additionalSourceDirs] - use `getAdditionalSourceDirs().setFrom()` instead.
* The `append` property on `JacocoTaskExtension` has been removed.
  `append` is now always configured to be true for the Jacoco agent.
* The `configureDefaultOutputPathForJacocoMerge` method on `JacocoPlugin` has been removed.
  The method was never meant to be public.
* File paths in link:{javadocPath}/org/gradle/plugins/ear/descriptor/DeploymentDescriptor.html#getFileName--[deployment descriptor file name] for the ear plugin are not allowed any more.
  Use a simple name, like `application.xml`, instead.
* The `org.gradle.testfixtures.ProjectBuilder` constructor has been removed. Please use `ProjectBuilder.builder()` instead.
* When <<groovy_plugin.adoc#sec:incremental_groovy_compilation,incremental Groovy compilation>> is enabled, a wrong configuration of the source roots or enabling Java annotation for Groovy now fails the build.
  Disable incremental Groovy compilation when you want to compile in those cases.
* `ComponentSelectionRule` no longer can inject the metadata or ivy descriptor.
  Use the methods on the <<resolution_rules.adoc#sec:component-selection-rules,`ComponentSelection` parameter>> instead.
* Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now an error.
  Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.
* The `getEffectiveAnnotationProcessorPath()` method is removed from the `JavaCompile` and `ScalaCompile` tasks.
* Changing the value of a task property with type `Property<T>` after the task has started execution now results in an error.
* The `isLegacyLayout()` method is removed from `SourceSetOutput`.
* The map returned by `TaskInputs.getProperties()` is now unmodifiable.
  Trying to modify it will result in an `UnsupportedOperationException` being thrown.
* There are slight changes in the incubating <<component_capabilities.adoc#sec:selecting-between-candidates,capabilities resolution>> API, which has been introduced in 5.6, to also allow variant selection based on variant name

[[changes_5.6]]
== Upgrading from 5.5 and earlier

=== Deprecations

==== Changing the contents of `ConfigurableFileCollection` task properties after task starts execution

When a task property has type `ConfigurableFileCollection`, then the file collection referenced by the property will ignore changes made to the contents of the collection once the task starts execution.
This has two benefits.
Firstly, this prevents accidental changes to the property value during task execution which can cause Gradle up-to-date checks and build cache lookup using different values to those used by the task action.
Secondly, this improves performance as Gradle can calculate the value once and cache the result.

This will become an error in Gradle 6.0.

==== Creating `SignOperation` instances

Creating `SignOperation` instances directly is now deprecated. Instead, the methods of `SigningExtension` should be used to create these instances.

This will become an error in Gradle 6.0.

==== Declaring an incremental task without outputs

Declaring an <<custom_tasks.adoc#incremental_tasks,incremental task>> without declaring outputs is now deprecated.
Declare file outputs or use link:{javadocPath}/org/gradle/api/tasks/TaskOutputs.html#upToDateWhen-groovy.lang.Closure-[TaskOutputs.upToDateWhen()] instead.

This will become an error in Gradle 6.0.

==== Method `WorkerExecutor.submit()` is deprecated

The `WorkerExecutor.submit()` method is now deprecated.
The new `noIsolation()`, `classLoaderIsolation()` and `processIsolation()` methods should now be used to submit work.
See <<worker_api.adoc#tasks_parallel_worker,the section on the Worker API>> for more information on using these methods.

`WorkerExecutor.submit()` will be removed in Gradle 8.0.

=== Potential breaking changes

==== Task dependencies are honored for task `@Input` properties whose value is a `Property`

Previously, task dependencies would be ignored for task `@Input` properties of type `Property<T>`.
These are now honored, so that it is possible to attach a task output property to a task `@Input` property.

This may introduce unexpected cycles in the task dependency graph, where the value of an output property is mapped to produce a value for an input property.

==== Declaring task dependencies using a file `Provider` that does not represent a task output

Previously, it was possible to pass `Task.dependsOn()` a `Provider<File>`, `Provider<RegularFile>` or `Provider<Directory>` instance that did not represent a task output.
These providers would be silently ignored.

This is now an error because Gradle does not know how to build files that are not task outputs.

*Note* that it is still possible to pass `Task.dependsOn()` a `Provider` that returns a file and that represents a task output, for example `myTask.dependsOn(jar.archiveFile)` or `myTask.dependsOn(taskProvider.flatMap { it.outputDirectory })`, when the `Provider` is an annotated `@OutputFile` or `@OutputDirectory` property of a task.

==== Setting `Property` value to `null` uses the property convention

Previously, calling `Property.set(null)` would always reset the value of the property to 'not defined'.
Now, the convention that is associated with the property using the `convention()` method will be used to determine the value of the property.

==== Enhanced validation of names for `publishing.publications` and `publishing.repositories`

The repository and publication names are used to construct task names for publishing. It was possible to supply a name that would result in an invalid task name.
Names for publications and repositories are now restricted to `[A-Za-z0-9_\\-.]+`.

==== Restricted Worker API classloader and process classpath

Gradle now prevents internal dependencies (like Guava) from leaking into the classpath used by Worker API actions.
This fixes link:https://github.com/gradle/gradle/issues/3698[an issue] where a worker needs to use a dependency that is also used by Gradle internally.

In previous releases, it was possible to rely on these leaked classes. Plugins relying on this behavior will now fail.
To fix the plugin, the worker should explicitly include all required dependencies in its classpath.

==== Default PMD version upgraded to 6.15.0

<<pmd_plugin#pmd_plugin, The PMD plugin>> has been upgraded to use link:https://pmd.github.io/pmd-6.15.0/pmd_release_notes.html[PMD version 6.15.0] instead of 6.8.0 by default.

Contributed by link:https://github.com/wreulicke[wreulicke]

==== Configuration copies have unique names

Previously, all copies of a configuration always had the name `<OriginConfigurationName>Copy`.
Now when creating multiple copies, each will have a unique name by adding an index starting from the second copy. (e.g. `CompileOnlyCopy2`)

==== Changed classpath filtering for Eclipse

Gradle 5.6 no longer supplies custom classpath attributes in the Eclipse model.
Instead, it provides the attributes for link:https://www.eclipse.org/eclipse/news/4.8/jdt.php#jdt-test-sources[Eclipse test sources].
This change requires Buildship version 3.1.1 or later.

==== Embedded Kotlin upgraded to 1.3.41

Gradle Kotlin DSL scripts and Gradle Plugins authored using the `kotlin-dsl` plugin are now compiled using Kotlin 1.3.41.

Please see the Kotlin link:https://blog.jetbrains.com/kotlin/2019/06/kotlin-1-3-40-released/[blog post] and link:https://github.com/JetBrains/kotlin/blob/1.3.40/ChangeLog.md[changelog] for more information about the included changes.

The minimum supported Kotlin Gradle Plugin version is now 1.2.31. Previously it was 1.2.21.

==== Automatic capability conflict resolution

Previous versions of Gradle would automatically select, in case of capability conflicts, the module which has the highest capability version.
Starting from 5.6, this is an opt-in behavior that can be activated using:

```
configurations.all {
   resolutionStrategy.capabilitiesResolution.all { selectHighestVersion() }
}
```

See <<component_capabilities.adoc#capabilities, the capabilities section of the documentation>> for more options.

==== File removal operations don't follow symlinked directories

When Gradle has to remove the output files of a task for various reasons, it will not follow symlinked directories.
The symlink itself will be deleted, but the contents of the linked directory will stay intact.

=== Disabled debug argument parsing in JavaExec

Gradle 5.6 introduced a new DSL element (`JavaForkOptions.debugOptions(Action<JavaDebugOptions>)`) to configure debug properties for forked Java processes.
Due to this change, Gradle no longer parses debug-related JVM arguments. Consequently, `JavaForkOptions.getDebu()` no longer returns `true` if the `-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005` or the `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005` argument is specified to the process.

=== Scala 2.9 and Zinc compiler

Gradle no longer supports building applications using Scala 2.9.

[[changes_5.5]]
== Upgrading from 5.4 and earlier

=== Deprecations

==== Play

The built-in <<play_plugin.adoc#play_plugin, Play plugin>> has been deprecated and will be replaced by a new link:https://gradle.github.io/playframework[Play Framework plugin] available from the plugin portal.

==== Build Comparison

The _build comparison_ plugin has been deprecated and will be removed in the next major version of Gradle.

link:https://gradle.com/build-scans[Build scans] show much deeper insights into your build and you can use link:https://gradle.com/develocity[Develocity] to directly compare two build's build-scans.

=== Potential breaking changes

==== User supplied Eclipse project names may be ignored on conflict

Project names configured via link:{javadocPath}/org/gradle/plugins/ide/eclipse/model/EclipseProject.html[`EclipseProject.setName(...)`] were honored by Gradle and Buildship in all cases, even when the names caused conflicts and import/synchronization errors.

Gradle can now deduplicate these names if they conflict with other project names in an Eclipse workspace.
This may lead to different Eclipse project names for projects with user-specified names.

The upcoming 3.1.1 version of Buildship is required to take advantage of this behavior.

Contributed by link:https://github.com/fraenkelc[Christian Fränkel]

==== Default JaCoCo version upgraded to 0.8.4

<<jacoco_plugin#jacoco_plugin, The JaCoCo plugin>> has been upgraded to use link:http://www.jacoco.org/jacoco/trunk/doc/changes.html[JaCoCo version 0.8.4] instead of 0.8.3 by default.

Contributed by link:https://github.com/Godin[Evgeny Mandrikov]

==== Embedded Ant version upgraded to 1.9.14

The version of Ant distributed with Gradle has been upgraded to link:https://archive.apache.org/dist/ant/RELEASE-NOTES-1.9.14.html[1.9.14] from 1.9.13.

==== Type `DependencyHandler` now statically exposes `ExtensionAware`

This affects Kotlin DSL build scripts that make use of `ExtensionAware` extension members such as the `extra` properties accessor inside the `dependencies {}` block.
The receiver for those members will no longer be the enclosing `Project` instance but the `dependencies` object itself, the innermost `ExtensionAware` conforming receiver.
In order to address `Project` extra properties inside `dependencies {}` the receiver must be explicitly qualified i.e. `project.extra` instead of just `extra`.
Affected extensions also include `the<T>()` and `configure<T>(T.() -> Unit)`.

==== Improved processing of dependency excludes

Previous versions of Gradle could, in some complex dependency graphs, have a wrong result or a randomized dependency order when lots of excludes were present.
To mitigate this, the algorithm that computes exclusions has been rewritten.
In some rare cases this may cause some differences in resolution, due to the correctness changes.

==== Improved classpath separation for worker processes

The system classpath for worker daemons started by the <<worker_api.adoc#worker_api, Worker API>> when using `PROCESS` isolation has been reduced to a minimum set of Gradle infrastructure.
User code is still segregated into a separate classloader to isolate it from the Gradle runtime.
This should be a transparent change for tasks using the worker API, but previous versions of Gradle mixed user code and Gradle internals in the worker process.
Worker actions that rely on things like the `java.class.path` system property may be affected, since `java.class.path` now represents only the classpath of the Gradle internals.

[[changes_5.4]]
== Upgrading from 5.3 and earlier

=== Deprecations

==== Using custom local build cache implementations

Using a custom build cache implementation for the local build cache is now deprecated.
The only allowed type will be `DirectoryBuildCache` going forward.
There is no change in the support for using custom build cache implementations as the remote build cache.

=== Potential breaking changes

==== Use HTTPS when configuring Google Hosted Libraries via `googleApis()`

The Google Hosted Libraries URL accessible via `JavaScriptRepositoriesExtension#GOOGLE_APIS_REPO_URL` was changed to use the HTTPS protocol.
The change also affect the Ivy repository configured via `googleApis()`.

[[changes_5.3]]
== Upgrading from 5.2 and earlier

=== Potential breaking changes

==== Bug fixes in platform resolution

There was a bug from Gradle 5.0 to 5.2.1 (included) where enforced platforms would potentially include dependencies instead of constraints.
This would happen whenever a POM file defined both dependencies and "constraints" (via `<dependencyManagement>`) and that you used `enforcedPlatform`.
Gradle 5.3 fixes this bug, meaning that you might have differences in the resolution result if you relied on this broken behavior.
Similarly, Gradle 5.3 will no longer try to download jars for `platform` and `enforcedPlatform` dependencies (as they should only bring in constraints).

==== Automatic target JVM version

If you apply any of the Java plugins, Gradle will now do its best to select dependencies which match the target compatibility of the module being compiled.
What it means, in practice, is that if you have module A built for Java 8, and module B built for Java 8, then there's no change.
However if B is built for Java 9+, then it's not binary compatible anymore, and Gradle would complain with an error message like the following:

```
Unable to find a matching variant of project :producer:
  - Variant 'apiElements' capability test:producer:unspecified:
      - Provides org.gradle.dependency.bundling 'external'
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found value 'java-api-jars'.
  - Variant 'runtimeElements' capability test:producer:unspecified:
      - Provides org.gradle.dependency.bundling 'external'
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found value 'java-runtime-jars'.
```

In general, this is a sign that your project is misconfigured and that your dependencies are not compatible.
However, there are cases where you still may want to do this, for example when only a _subset_ of classes of your module actually need the Java 9 dependencies, and are not intended to be used on earlier releases.
Java in general doesn't encourage you to do this (you should split your module instead), but if you face this problem, you can workaround by disabling this new behavior on the consumer side:

```
java {
   disableAutoTargetJvm()
}
```

==== Bug fix in Maven / Ivy interoperability with dependency substitution

If you have a Maven dependency pointing to an Ivy dependency where the `default` configuration dependencies do not match the `compile` + `runtime` + `master` ones
_and_ that Ivy dependency was substituted (using a `resolutionStrategy.force`, `resolutionStrategy.eachDependency` or `resolutionStrategy.dependencySubstitution`)
then this fix will impact you.
The legacy behaviour of Gradle, prior to 5.0, was still in place instead of being replaced by the changes introduced by improved pom support.

==== Delete operations correctly handle symbolic links on Windows

Gradle no longer ignores the `followSymlink` option on Windows for the `clean` task, all `Delete` tasks, and `project.delete {}` operations in the presence of junction points and symbolic links.

==== Fix in publication of additional artifacts

In previous Gradle versions, additional artifacts registered at the project level were not published by `maven-publish` or `ivy-publish` unless they were also added as artifacts in the publication configuration.

With Gradle 5.3, these artifacts are now properly accounted for and published.

This means that artifacts that are registered both on the project _and_ the publication, Ivy or Maven, will cause publication to fail since it will create duplicate entries.
The fix is to remove these artifacts from the publication configuration.

[[changes_5.2]]
== Upgrading from 5.1 and earlier

=== Potential breaking changes

none

[[changes_5.1]]
== Upgrading from 5.0 and earlier

=== Deprecations

Follow the API links to learn how to deal with these deprecations (if no extra information is provided here):

 * Setters for `classes` and `classpath` on `org.gradle.plugin.devel.tasks.ValidateTaskProperties` (removed)

 * There should not be setters for lazy properties like link:{javadocPath}/org/gradle/api/file/ConfigurableFileCollection.html[`ConfigurableFileCollection`].  Use `setFrom` instead. For example,
----
    validateTaskProperties.getClasses().setFrom(fileCollection)
    validateTaskProperties.getClasspath().setFrom(fileCollection)
----

=== Potential breaking changes

The following changes were not previously deprecated:

==== Signing API changes
Input and output files of `Sign` tasks are now tracked via `Signature.getToSign()` and `Signature.getFile()`, respectively.

==== Collection properties default to empty collection

In Gradle 5.0, the collection property instances created using `ObjectFactory` would have no value defined, requiring plugin authors to explicitly set an initial value. This proved to be awkward and error prone so `ObjectFactory` now returns instances with an empty collection as their initial value.

==== Worker API: working directory of a worker can no longer be set

Since JDK 11 no longer supports changing the working directory of a running process, setting the working directory of a worker via its fork options is now prohibited.
All workers now use the same working directory to enable reuse.
Please pass files and directories as arguments instead. See examples in the <<worker_api.adoc#worker_api, Worker API documentation>>.

==== Changes to native linking tasks

To expand our idiomatic <<lazy_configuration.adoc#lazy_configuration, Provider API>> practices, the install name property from `org.gradle.nativeplatform.tasks.LinkSharedLibrary` is affected by this change.

- `getInstallName()` was changed to return a `Property`.
- `setInstallName(String)` was removed. Use `Property.set()` instead.

==== Passing arguments to Windows Resource Compiler

To expand our idiomatic <<lazy_configuration.adoc#lazy_configuration, Provider API>> practices, the `WindowsResourceCompile` task has been converted to use the Provider API.

Passing additional compiler arguments now follow the same pattern as the `CppCompile` and other tasks.

==== Copied configuration no longer shares a list of `beforeResolve` actions with original

The list of `beforeResolve` actions are no longer shared between a copied configuration and the original.
Instead, a copied configuration receives a copy of the `beforeResolve` actions at the time the copy is made.
Any `beforeResolve` actions added after copying (to either configuration) will not be shared between the original and the copy.
This may break plugins that relied on the previous behaviour.

==== Changes to incubating POM customization types

- The type of `MavenPomDeveloper.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.
- The type of `MavenPomContributor.properties` has changed from `Property<Map<String, String>>` to `MapProperty<String, String>`.

==== Changes to specifying operating system for native projects

The incubating `operatingSystems` property on native components has been replaced with the link:{javadocPath}/org/gradle/language/cpp/CppComponent.html#getTargetMachines()[targetMachines] property.

==== Changes for archive tasks (`Zip`, `Jar`, `War`, `Ear`, `Tar`)

===== Change in behavior for tasks extending `AbstractArchiveTask`

The `AbstractArchiveTask` has several new properties using the <<lazy_configuration.adoc#lazy_configuration_reference,Provider API>>.
Plugins that extend these types and override methods from the base class may no longer behave the same way.
Internally, `AbstractArchiveTask` prefers the new properties and methods like `getArchiveName()` are façades over the new properties.

If your plugin/build only uses these types (and does not extend them), nothing has changed.
