Upgrading your build from Gradle 4.x to 5.0

The changes in this section have the potential to break your build, but the vast majority have been deprecated for quite some time and few builds will be affected by a large number of them. We strongly recommend upgrading to Gradle 4.10 first to get a report on what deprecations affect your build.

The following breaking changes are not from deprecations, but the result of changes in behavior:

The following breaking changes will appear as deprecation warnings with Gradle 4.10:

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

Prior to this release, builds were allowed to replace built-in tasks. This feature has been deprecated.

The full list of built-in tasks that should not be replaced is: wrapper, init, help, tasks, projects, buildEnvironment, components, dependencies, dependencyInsight, dependentComponents, model, properties.

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

The command line client now starts with 64MB of heap instead of 1GB. This may affect builds running directly inside the client VM using --no-daemon mode. We discourage the use of --no-daemon, but if you must use it, you can increase the available memory using the GRADLE_OPTS environment variable.

The Gradle daemon now starts with 512MB of heap instead of 1GB. Large projects may have to increase this setting using the org.gradle.jvmargs property.

All workers, including compilers and test executors, now start with 512MB of heap. The previous default was 1/4th of physical memory. Large projects may have to increase this setting on the relevant tasks, e.g. JavaCompile or Test.

The default tool versions of the following code quality plugins have been updated:

Several libraries that are used by Gradle have been upgraded:

Through the Gradle 4.x release stream, new @Incubating features were added to the dependency resolution engine. These include sophisticated version constraints (prefer, strictly, reject), dependency constraints, and platform dependencies.

If you have been using the IMPROVED_POM_SUPPORT feature preview, playing with constraints or prefer, reject and other specific version indications, then make sure to take a good look at your dependency resolution results.

Gradle now provides support for importing bill of materials (BOM) files, which are effectively POM files that use <dependencyManagement> sections to control the versions of direct and transitive dependencies. All you need to do is declare the POM as a platform dependency.

The following example picks the versions of the gson and dom4j dependencies from the declared Spring Boot BOM:

Since Gradle 1.0, runtime-scoped dependencies have been included in the Java compilation classpath, which has some drawbacks:

With this new behavior, the Java and Java Library plugins both honor the separation of compile and runtime scopes. This means that the compilation classpath only includes compile-scoped dependencies, while the runtime classpath adds the runtime-scoped dependencies as well. This is particularly useful if you develop and publish Java libraries with Gradle where the separation between api and implementation dependencies is reflected in the published scopes.

In order to use S3 backed artifact repositories, you previously had to add --add-modules java.xml.bind to org.gradle.jvmargs when running on Java 9 and above.

Since Java 11 no longer contains the java.xml.bind module, Gradle now bundles JAXB 2.3.1 (com.sun.xml.bind:jaxb-impl) and uses it on Java 9 and above.

Please remove the --add-modules java.xml.bind option from org.gradle.jvmargs, if set.

With this new behavior, if a plugin or a transitive dependency of a plugin found in the gradlePluginPortal() repository has no Maven POM it will fail to resolve.

Artifacts published to a Maven repository without a POM should be fixed. If you encounter such artifacts, please ask the plugin or library author to publish a new version with proper metadata.

If you are stuck with a bad plugin, you can work around by re-enabling JARs as metadata source for the gradlePluginPortal() repository:

The Java Library Distribution Plugin is now based on the Java Library Plugin instead of the Java Plugin.

Additionally, the default distribution created by the plugin will contain all artifacts of the runtimeClasspath configuration instead of the deprecated runtime configuration.

The configuration avoidance API introduced in Gradle 4.9 allows you to avoid creating and configuring tasks that are never used.

With the existing API, this example adds two tasks (foo and bar):

When converting this to use the new API, something surprising happens: bar doesn’t exist. The new API only executes configuration actions when necessary, so the register() for task bar only executes when foo is configured.

To avoid this, Gradle now detects this and prevents modification to the underlying container (through create() or register()) when using the new API.

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.

The S3 repository transport protocol allows Gradle to publish artifacts to AWS S3 buckets. Starting with this release, every artifact uploaded to an S3 bucket will be equipped with the bucket-owner-full-control canned ACL. Make sure that the AWS account used to publish artifacts has the s3:PutObjectAcl and s3:PutObjectVersionAcl permissions, otherwise the upload will fail.

See AWS S3 Cross Account Access for more information.

Gradle 4.9 introduced a new way to create and configure tasks that works lazily. When you use this approach for tasks that are expensive to configure, or when you have many, many tasks, your build configuration time can drop significantly when those tasks don’t run.

You can learn more about lazily creating tasks in the Task Configuration Avoidance chapter. You can also read about the background to this new feature in this blog post.

Now that the publishing plugins are stable, we recommend that you migrate from the legacy publishing mechanism for standard Java projects, i.e. those based on the Java Plugin. That includes projects that use any one of: Java Library Plugin, Application Plugin or War Plugin.

To use the new approach, simply replace any upload<Conf> configuration with a publishing {} block. See the publishing overview chapter for more information.

Prior to Gradle 4.8, the publishing {} block was implicitly treated as if all the logic inside it was executed after the project was evaluated. This was confusing, because it was the only block that behaved that way. As part of the stabilization effort in Gradle 4.8, we are deprecating this behavior and asking all users to migrate their build.

The new, stable behavior can be switched on by adding the following to your settings file:

We recommend doing a test run with a local repository to see whether all artifacts still have the expected coordinates. In most cases everything should work as before and you are done. However, your publishing block may rely on the implicit deferred configuration, particularly if it relies on values that may change during the configuration phase of the build.

For example, under the new behavior, the following logic assumes that jar.archiveBaseName doesn’t change after artifactId is set:

If that assumption is incorrect or might possibly be incorrect in the future, the artifactId must be set within an afterEvaluate {} block, like so:

You should no longer define your own wrapper and init tasks. Configure the existing tasks instead, for example by converting this:

to this:

If an exclusion in a Maven POM was missing either a groupId or artifactId, Gradle used to ignore the exclusion. Now the missing elements are treated as implicit wildcards — e.g. <groupId>*</groupId> — which means that some of your dependencies may now be excluded where they weren’t before.

You will need to explicitly declare any missing dependencies that you need.

The plain console mode now formats output consistently with the rich console, which means that the output format has changed. For example:

This may break tools that scrape details from the plain console output.

Many tasks related to compiling, linking and installing native libraries and applications have been converted to the Provider API so that they support lazy configuration. This conversion has introduced some breaking changes to the APIs of the tasks so that they match the conventions of the Provider API.

The following tasks have been changed:

The following have also seen similar changes:

VisualStudioExtension no longer has a solutions property. Instead, you configure a single solution via VisualStudioRootExtension in the root project, like so:

In addition, there are no longer individual tasks to generate the solution files for each component, but rather a single visualStudio task that generates a solution file that encompasses all components in the build.

When connecting to an HTTP build cache backend via HttpBuildCache, Gradle does not follow redirects any more, treating them as errors instead. Getting a redirect from the build cache backend is mostly a configuration error — using an "http" URL instead of "https" for example — and has negative effects on performance.

This version includes several upgrades of third-party dependencies:

This fix the following security issues:

Gradle does not expose public APIs for these 3rd-party dependencies, but those who customize Gradle will want to be aware.