// Copyright 2018 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_5]]
= Upgrading your build from Gradle 5.x

This chapter provides the information you need to migrate your Gradle 5.x builds to Gradle {gradleVersion}. 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 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_5.6]]
== Upgrading from 5.5 and earlier

=== Deprecations

==== BuildSrc usage in Gradle settings

Access to the buildSrc project and its dependencies in gradle settings scripts is now deprecated.
This is due to plans to make initialization of gradle builds more efficient.

This will become an error in Gradle 6.0.

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

==== `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 <<custom_tasks.html#using-the-worker-api, the userguide>> for more information on using these methods.

`WorkerExecutor.submit()` will be removed in Gradle 7.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 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() }
}
```

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


See <<managing_transitive_dependencies.adoc#sec:capabilities, the capabilities section of the documentation>> for more options.

[[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 <<comparing_builds.adoc#comparing_builds, 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/[Gradle Enterprise] 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.

==== `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 <<custom_tasks.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:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible value 'java-api-jars'.
  - Variant 'runtimeElements' capability test:producer:unspecified:
      - Required org.gradle.dependency.bundling 'external' and found compatible value 'external'.
      - Required org.gradle.jvm.version '8' and found incompatible value '9'.
      - Required org.gradle.usage 'java-api' and found compatible 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 link:{javadocPath}/org/gradle/plugin/devel/tasks/ValidateTaskProperties.html[`ValidateTaskProperties`]

 * 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 <<custom_tasks.adoc#worker_api, Worker API documentation>>.

==== Changes to native linking tasks

To expand our idiomatic <<lazy_configuration.adoc#, 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#, 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.

==== Change in behavior for tasks extending `AbstractArchiveTask` or subtypes (`Zip`, `Jar`, `War`, `Ear`, `Tar`)

The `AbstractArchiveTask` has several new properties using the <<lazy_configuration.adoc#provider-files-api-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.

////
== Changes in detail

[[rel5.X:title]]
=== [5.X] Title

Details...
////
