# Upgrading your build from Gradle 5.x

This chapter provides the information you need to migrate your Gradle 5.x builds to Gradle 5.3.1. For migrating from Gradle 4.x, complete the 4.x to 5.0 guide first.

We recommend the following steps for all users:

1. Try running `gradle help --scan` and view the deprecations view of the generated 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.

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

3. Run `gradle wrapper --gradle-version 5.3.1` to update the project to 5.3.1.

4. Try to run the project and debug any errors using the Troubleshooting Guide.

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

## Upgrading from 5.1 and earlier

### Potential breaking changes

none

## Upgrading from 5.0 and earlier

### 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 documentation.

#### Changes to native linking tasks

To expand our idiomatic 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 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 targetMachines property.

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

The `AbstractArchiveTask` has several new properties using the 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.

### Deprecated classes, methods and properties

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 `ValidateTaskProperties`

- There should not be setters for lazy properties like `ConfigurableFileCollection`. Use `setFrom` instead. For example,

        validateTaskProperties.getClasses().setFrom(fileCollection)
        validateTaskProperties.getClasspath().setFrom(fileCollection)