Upgrading your build from Gradle 6.x to the latest
This chapter provides the information you need to migrate your Gradle 6.x builds to the latest Gradle release. For migrating from Gradle 4.x or 5.x, see the older migration guide first.
We recommend the following steps for all users:
-
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. -
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.6-rc-2
to update the project to 6.6-rc-2. -
Try to run the project and debug any errors using the Troubleshooting Guide.
Upgrading from 6.5
Potential breaking changes
Updates to bundled Gradle dependencies
-
Ant has been updated to 1.10.8.
-
Groovy has been updated to Groovy 2.5.12.
Deprecations
No deprecations were made in Gradle 6.6.
Upgrading from 6.4
Potential breaking changes
Updates to bundled Gradle dependencies
-
Kotlin has been updated to Kotlin 1.3.72.
-
Groovy has been updated to Groovy 2.5.11.
Updates to default tool integration versions
-
PMD has been updated to PMD 6.23.0.
Deprecations
Internal class AbstractTask is deprecated
AbstractTask
is an internal class which is visible on the public API, as a superclass of public type DefaultTask
.
AbstractTask
will be removed in Gradle 7.0, and the following are deprecated in Gradle 6.5:
-
Registering a task whose type is
AbstractTask
orTaskInternal
. You can remove the task type from the task registration and Gradle will useDefaultTask
instead. -
Registering a task whose type is a subclass of
AbstractTask
but not a subclass ofDefaultTask
. You can change the task type to extendDefaultTask
instead. -
Using the class
AbstractTask
from plugin code or build scripts. You can change the code to useDefaultTask
instead.
Upgrading from 6.3
Potential breaking changes
PMD plugin expects PMD 6.0.0 or higher by default
Gradle 6.4 enabled incremental analysis by default. Incremental analysis is only available in PMD 6.0.0 or higher. If you want to use an older PMD version, you need to disable incremental analysis:
pmd {
incrementalAnalysis = false
}
Changes in dependency locking
With Gradle 6.4, the incubating API for dependency locking LockMode
has changed.
The value is now set via a Property<LockMode>
instead of a direct setter.
This means that the notation to set the value has to be updated for the Kotlin DSL:
dependencyLocking {
lockMode.set(LockMode.STRICT)
}
Users of the Groovy DSL should not be impacted as the notation lockMode = LockMode.STRICT
remains valid.
Java versions in published metadata
If a Java library is published with Gradle Module Metadata, the information which Java version it supports is encoded in the org.gradle.jvm.version
attribute.
By default, this attribute was set to what you configured in java.targetCompatibility
.
If that was not configured, it was set to the current Java version running Gradle.
Changing the version of a particular compile task, e.g. javaCompile.targetCompatibility
had no effect on that attribute, leading to wrong information if the attribute was not adjusted manually.
This is now fixed and the attribute defaults to the setting of the compile task that is associated with the sources from which the published jar is built.
Ivy repositories with custom layouts
Gradle versions from 6.0 to 6.3.x included could generate bad Gradle Module Metadata when publishing on an Ivy repository which had a custom repository layout. Starting from 6.4, Gradle will no longer publish Gradle Module Metadata if it detects that you are using a custom repository layout.
New properties may shadow variables in build scripts
This release introduces some new properties — mainClass
, mainModule
, modularity
— in different places.
Since these are very generic names, there is a chance that you use one of them in your build scripts as variable name.
A new property might then shadow one of your variables in an undesired way, leading to a build failure where the property is accessed instead of the local variable with the same name.
You can fix it by renaming the corresponding variable in the build script.
Affected is configuration code inside the application {}
and java {}
configuration blocks, inside a java execution setup with project.javaexec {}
, and inside various task configurations
(JavaExec
, CreateStartScripts
, JavaCompile
, Test
, Javadoc
).
Updates to bundled Gradle dependencies
-
Kotlin has been updated to Kotlin 1.3.71.
Deprecations
There were no deprecations between Gradle 6.3 and 6.4.
Upgrading from 6.2
Potential breaking changes
Fewer dependencies available in IDEA
Gradle no longer includes the annotation processor classpath as provided dependencies in IDEA.
The dependencies IDEA sees at compile time are the same as what Gradle sees after resolving the compile classpath (configuration named compileClasspath
).
This prevents the leakage of annotation processor dependencies into the project’s code.
Before Gradle introduced incremental annotation processing support, IDEA required all annotation processors to be on the compilation classpath to be able to run annotation processing when compiling in IDEA. This is no longer necessary because Gradle has a separate annotation processor classpath. The dependencies for annotation processors are not added to an IDEA module’s classpath when a Gradle project with annotation processors is imported.
Updates to bundled Gradle dependencies
-
Kotlin has been updated to Kotlin 1.3.70.
-
Groovy has been updated to Groovy 2.5.10.
Updates to default tool integration versions
-
PMD has been updated to PMD 6.21.0.
-
CodeNarc has been updated to CodeNarc 1.5.
Rich console support removed for some 32-bit operating systems
Gradle 6.3 does not support the rich console for 32-bit Unix systems and for old FreeBSD versions (older than FreeBSD 10). Microsoft Windows 32-bit is unaffected.
Gradle will continue building projects on 32-bit systems but will no longer show the rich console.
Deprecations
Using default and archives configurations
Almost every Gradle project has the default and archives configurations which are added by the base plugin. These configurations are no longer used in modern Gradle builds that use variant aware dependency management and the new publishing plugins.
While the configurations will stay in Gradle for backwards compatibility for now, using them to declare dependencies or to resolve dependencies is now deprecated.
Resolving these configurations was never an intended use case and only possible because in earlier Gradle versions every configuration was resolvable. For declaring dependencies, please use the configurations provided by the plugins you use, for example by the Java Library plugin.
Upgrading from 6.1
Potential breaking changes
Compile and runtime classpath now request library variants by default
A classpath in a JVM project now explicitly requests the org.gradle.category=library
attribute.
This leads to clearer error messages if a certain library cannot be used.
For example, when the library does not support the required Java version.
The practical effect is that now all platform dependencies have to be declared as such.
Before, platform dependencies also worked, accidentally, when the platform()
keyword was omitted for local platforms or platforms published with Gradle Module Metadata.
Properties from project root gradle.properties
leaking into buildSrc
and included builds
There was a regression in Gradle 6.2 and Gradle 6.2.1 that caused Gradle properties set in the project root gradle.properties
file to leak into the buildSrc
build and any builds included by the root.
This could cause your build to start failing if the buildSrc
build or an included build suddenly found an unexpected or incompatible value for a property coming from the project root gradle.properties
file.
The regression has been fixed in Gradle 6.2.2.
Deprecations
There were no deprecations between Gradle 6.1 and 6.2.
Upgrading from 6.0 and earlier
Deprecations
Querying a mapped output property of a task before the task has completed
Querying the value of a mapped output property before the task has completed can cause strange build failures because it indicates stale or non-existent outputs may be used by mistake. This behavior is deprecated and will emit a deprecation warning. This will become an error in Gradle 7.0.
The following example demonstrates this problem where the Producer’s output file is parsed before the Producer executes:
class Consumer extends DefaultTask {
@Input
final Property<Integer> threadPoolSize = ...
}
class Producer extends DefaultTask {
@OutputFile
final RegularFileProperty outputFile = ...
}
// threadPoolSize is read from the producer's outputFile
consumer.threadPoolSize = producer.outputFile.map { it.text.toInteger() }
// Emits deprecation warning
println("thread pool size = " + consumer.threadPoolSize.get())
Querying the value of consumer.threadPoolSize
will produce a deprecation warning if done prior to producer
completing, as the output file has not yet been generated.
Discontinued methods
The following methods have been discontinued and should no longer be used. They will be removed in Gradle 7.0.
-
BasePluginConvention.setProject(ProjectInternal)
-
BasePluginConvention.getProject()
-
StartParameter.useEmptySettings()
-
StartParameter.isUseEmptySettings()
Alternative JVM plugins (a.k.a "Software Model")
A set of alternative plugins for Java and Scala development were introduced in Gradle 2.x as an experiment based on the "software model". These plugins are now deprecated and will eventually be removed. If you are still using one of these old plugins (java-lang
, scala-lang
, jvm-component
, jvm-resources
, junit-test-suite
) please consult the documentation on Building Java & JVM projects to determine which of the stable JVM plugins are appropriate for your project.
Potential breaking changes
ProjectLayout
is no longer available to worker actions as a service
In Gradle 6.0, the ProjectLayout
service was made available to worker actions via service injection. This service allowed for mutable state to leak into a worker action and introduced a way for dependencies to go undeclared in the worker action.
ProjectLayout
has been removed from the available services. Worker actions that were using ProjectLayout
should switch to injecting the projectDirectory
or buildDirectory
as a parameter instead.
Updates to bundled Gradle dependencies
-
Kotlin has been updated to Kotlin 1.3.61.
Updates to default tool integration versions
-
Checkstyle has been updated to Checkstyle 8.27.
-
PMD has been updated to PMD 6.20.0.
Publishing Spring Boot applications
Starting from Gradle 6.2, Gradle performs a sanity check before uploading, to make sure you don’t upload stale files (files produced by another build).
This introduces a problem with Spring Boot applications which are uploaded using the components.java
component:
Artifact my-application-0.0.1-SNAPSHOT.jar wasn't produced by this build.
This is caused by the fact that the main jar
task is disabled by the Spring Boot application, and the component expects it to be present.
Because the bootJar
task uses the same file as the main jar
task by default, previous releases of Gradle would either:
-
publish a stale
bootJar
artifact -
or fail if the
bootJar
task hasn’t been called previously
A workaround is to tell Gradle what to upload.
If you want to upload the bootJar
, then you need to configure the outgoing configurations to do this:
configurations {
[apiElements, runtimeElements].each {
it.outgoing.artifacts.removeIf { it.buildDependencies.getDependencies(null).contains(jar) }
it.outgoing.artifact(bootJar)
}
}
Alternatively, you might want to re-enable the jar
task, and add the bootJar
with a different classifier.
jar {
enabled = true
}
bootJar {
classifier = 'application'
}