How to update gradle
How to update gradle
Upgrading your build from Gradle 4.x to 5.0
This chapter provides the information you need to migrate your older Gradle 4.x builds to Gradle 5.0. In most cases, you will need to apply the changes from all versions that come after the one you’re upgrading from. For example, if you’re upgrading from Gradle 4.3 to 5.0, you will also need to apply the changes since 4.4, 4.5, etc up to 5.0.
| If you are using Gradle for Android, you need to move to version 3.3 or higher of both the Android Gradle Plugin and Android Studio. |
For all users
If you are not already on the latest 4.10.x release, read the sections below for help upgrading your project to the latest 4.10.x release. We recommend upgrading to the latest 4.10.x release to get the most useful warnings and deprecations information before moving to 5.0. Avoid upgrading Gradle and migrating to Kotlin DSL at the same time in order to ease troubleshooting in case of potential issues.
This is so that you can see any deprecation warnings that apply to your build. Gradle 5.x will generate (potentially less obvious) errors if you try to upgrade directly to it.
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.
In particular, you will need to use at least a 2.x version of the Shadow Plugin.
Move to Java 8 or higher if you haven’t already. Whereas Gradle 4.x requires Java 7, Gradle 5 requires Java 8 to run.
Read the Upgrading from 4.10 section and make any necessary changes.
Try to run the project and debug any errors using the Troubleshooting Guide.
In addition, Gradle has added several significant new and improved features that you should consider using in your builds:
Use native BOM import in your builds.
The Worker API for enabling units of work to run in parallel.
A new API for creating and configuring tasks lazily that can significantly improve your build’s configuration time.
Other notable changes to be aware of that may break your build include:
A change that means you should configure existing wrapper and init tasks rather than defining your own.
The honoring of implicit wildcards in Maven POM exclusions, which may result in dependencies being excluded that weren’t before.
The default memory settings for the command-line client, the Gradle daemon, and all workers including compilers and test executors, have been greatly reduced.
Upgrading from 4.10 and earlier
If you are not already on version 4.10, skip down to the section that applies to your current Gradle version and work your way up until you reach here. Then, apply these changes when moving from Gradle 4.10 to 5.0.
Other changes
The enableFeaturePreview(‘IMPROVED_POM_SUPPORT’) and enableFeaturePreview(‘STABLE_PUBLISHING’) flags are no longer necessary. These features are now enabled by default.
Potential breaking changes
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 evaluation of the publishing <> block is no longer deferred until needed but behaves like any other block. Please use afterEvaluate <> if you need to defer evaluation.
The Javadoc and Groovydoc tasks now delete the destination dir for the documentation before executing. This has been added to remove stale output files from the last task execution.
While it applies the Java Plugin, it behaves slightly different (e.g. it adds the api configuration). Thus, make sure to check whether your build behaves as expected after upgrading.
The html property on CheckstyleReport and FindBugsReport now returns a CustomizableHtmlReport instance that is easier to configure from statically typed languages like Java and Kotlin.
The Configuration Avoidance API has been updated to prevent the creation and configuration of tasks that are never used.
The default memory settings for the command-line client, the Gradle daemon, and all workers including compilers and test executors, have been greatly reduced.
The following breaking changes will appear as deprecation warnings with Gradle 4.10:
Use the Task.doLast() method instead, like this:
As mentioned before, Gradle can no longer be run on Java 7. However, you can still use forked compilation and testing to build and test software for Java 6 and above.
You can no longer have a Gradle build nested in a subdirectory of another Gradle build unless the nested build has a settings.gradle file.
The DirectoryBuildCache.setTargetSizeInMB(long) method has been removed — use DirectoryBuildCache.removeUnusedEntriesAfterDays instead.
The org.gradle.readLoggingConfigFile system property no longer does anything — update affected tests to work with your java.util.logging settings.
You can no longer cast FileCollection objects to other types using the as keyword or the asType() method.
You can no longer pass null as the configuration action of CopySpec.from(Object, Action).
For better compatibility with the Kotlin DSL, CopySpec.duplicatesStrategy is no longer nullable. The property setter no longer accepts null as a way to reset the property back to its default value. Use DuplicatesStrategy.INHERIT instead.
The FileCollection.stopExecutionIfEmpty() method has been removed — use the @SkipWhenEmpty annotation on FileCollection task properties instead.
The FileCollection.add() method has been removed — use Project.files() and Project.fileTree() to create configurable file collections/file trees and add to them via ConfigurableFileCollection.from().
SimpleFileCollection has been removed — use Project.files(Object…) instead.
Don’t have your own classes extend AbstractFileCollection — use the Project.files() method instead. This problem may exhibit as a missing getBuildDependencies() method.
The CompileOptions.bootClasspath property has been removed — use CompileOptions.bootstrapClasspath instead.
Gradle will no longer automatically apply annotation processors that are on the compile classpath — use CompileOptions.annotationProcessorPath instead.
The testClassesDir property has been removed from the Test task — use testClassesDirs instead.
The classesDir property has been removed from both the JDepend task and SourceSetOutput. Use the JDepend.classesDirs and SourceSetOutput.classesDirs properties instead.
The JavaLibrary(PublishArtifact, DependencySet) constructor has been removed — this was used by the Shadow Plugin, so make sure you upgrade to at least version 2.x of that plugin.
The JavaBasePlugin.configureForSourceSet() method has been removed.
The Maven Plugin used to publish the highly outdated Maven 2 metadata format. This has been changed and it will now publish Maven 3 metadata, just like the Maven Publish Plugin.
With the removal of Maven 2 support, the methods that configure unique snapshot behavior have also been removed. Maven 3 only supports unique snapshots, so we decided to remove them.
How to update Gradle
Last Updated on March 17, 2021
Using the Gradle wrapper means that a project can be fixed to a specific version of Gradle. If you want to update Gradle to a newer version though, follow the simple steps in this article.
What’s my current Gradle version?
What updated Gradle version can I use?
You can go to the Gradle releases page to find the latest version.
If you’re using Java just remember that what Java version you want to build your project with influences what Gradle version you should choose:
| Highest supported Java version | Gradle versions |
|---|---|
| 15 | Not yet supported |
| 14 | 6.3 – 6.5 |
| 13 | 6.0 – 6.2.2 |
| 11 | 5.0 – 5.6.4 |
| 10 | 4.7 – 4.10.3 |
| 9 | 4.2.1 – 4.6 |
How do I update my Gradle version?
Commit all the changed files into version control. If you’re using git then the list should look like this when you run git status :
That’s it! You’re all upgraded onto the new Gradle version. ✅
How does the version update actually work?
If you’re curious as to how that worked, read on.
Gradle uses the distributionUrl property to download the new version of Gradle and stores it in your user home directory in
/.gradle/wrapper/dists. The gradle-wrapper.jar file is used to do the actual download of the distribution.
For even more details about how the Gradle wrapper works, check out the article What is the Gradle wrapper and why should you use it?.
Resources
✅ if you prefer to learn in video format, check out the accompanying video on the Tom Gregory Tech YouTube channel.
Want to learn more about Gradle?
Check out the full selection of Gradle tutorials.
How to Efficiently Upgrade to Latest Version of Gradle
Gradle is a great build tool which allows you to write versatile build code to achieve whatever you want. The biggest drawback for me is the velocity of the Gradle releases and the corresponding breaking changes. You may say that one major release a year is ok but I currently manage tens of small open-sourced projects for me build script is something I should barely be touched except adding dependencies and new subprojects. So the need to upgrade happens only once in a couple of years and obviously not the only one as most of the projects on GitHub are still using Gradle 4.x:
I usually face a storm of issues from the build when I try to get the latest possible Gradle version working. Jumping form a very old version to the newest one is obviously not a good way to go. It’s always better to move stepwise so I took GitHub Actions for a rescue.
Stepwise Gradle Upgrade with Gradle Actions
Following steps could be achieved with any continuous integration tool but GitHub Actions allow to run much more parallel jobs at once than other available CI servers I know (at least for free).
Setting up GitHub Action Workflow
The idea is to run your project against every possible minor version of Gradle between the one currently present in the project ( 4.7 ) and the latest one ( 6.0.1 as a time of writing) to find you the which version still working with the current setup. You may argue that it would be enough to just use the major versions but there might be some consequences (e.g. upgrade of static analysis tools) which may also happen in minor versions.
The workflow checks out the code then it installs Java and it runs Gradle check task for all versions we are interested in. This may not fully guarantee that the other tasks such as deployment will work but it should detect most of the problems.
When all the jobs are finished in my project I have got the following results:
You should also remove the already passing version numbers from the matrix because they are no longer needed:
Then commit the changes in case of that you will need to revert some changes.
Stepwise Migration
Now there’s a time to fix the problem for the first failing version. You may get the good picture of what’s wrong simply by expanding the outputs in the GitHub Actions console. Also, the deprecation notes from the last working version may help. If the logs are not descriptive enough you can always use SDKMAN once again to run the build locally against different version than the wrapper one.
I will summarize some changes that my project required in the next section but each project is quite unique so you will probably face a suite of very different issues depending on which features and plugins you are using.
You repeat the steps unless you reach only the currently latest released version
Once you reach the latest version you can easily remove the matrix and gradle-version from the workflow file:
To be sure that you won’t fall behind the Gradle releases I would suggest you create a separate workflow file gradle-versions-watchdog.yml which will be triggered regularly. scheduled configuration will run once a month which is useful for projects which barely changes but you still want to keep Gradle versions up to date as rc is the latest release candidate version which is currently available.
The Story of One Upgrade
I have created this guide based on my experience of upgrading Gradle for Micronaut Libraries project. The build was pretty simple and consists of
These are pretty common tasks which you can find in most of the open-source projects. There is even a great bunch of plugins called Kordamp which simplifies most of the tasks mentioned. It also provides test aggregation task which wast the reason I have been doing the migration.
I was expecting a lot of problems with the incompatible plugins but I only had to give up on JaCoCo Full Report Plugin which is no longer supported in Gradle 6. I was willing to sacrifice that one as I want to migrate to Kordamp once the upgrade is finished and it provides the same functionality.
So the first issue was pretty trivial to fix — since 5.x there are no special characters allowed in the project name so I had to fix these.
Another issue was caused by the upgrade of CheckStyle with breaking changes in the configuration file. And of course, fixing the new default checks such as parentheses around lambda parameters.
A different story is the changed dependency resolution mechanism. To make the story short — Gradle 5.x won’t resolve the transitive dependencies correctly for libraries published with Gradle 4.x and older as they used to be published with a wrong Maven scope.
This was the last step of the upgrade which were needed for the particular project. There are no significant notable improvements but on the other hand, there are significant losses in terms of functionality which is no longer supported and needs to be migrated such as publishing the code coverage.
Summary
Keeping the build tool up to date is an unimportant task for many small projects. The gains are not obvious compared to the time which is spent on performing the upgrade and which can be spent on some more useful tasks. It can easily happen that you will have to sacrifice some of the functionality of your current build as there is also a lot of open-source plugins which failed to keep the pace with Gradle’s release cycle.
I’m currently putting hope to the Kordamp plugin suite which eliminates part of the flexibility of Gradle but should builds which are easier to maintain and less vulnerable to break during the upgrades. I will summarize the migration in another post if I succeed.
Revision History
2019–12–12: Suggested to create separate workflow file for regular Gradle RC checks.
Upgrading your build from Gradle 7.x to the latest
This chapter provides the information you need to migrate your Gradle 7.x builds to the latest Gradle release. For migrating from Gradle 4.x, 5.x, or 6.x, see the older migration guide first.
We recommend the following steps for all users:
This is so that you can see any deprecation warnings that apply to your build.
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.
Try to run the project and debug any errors using the Troubleshooting Guide.
Upgrading from 7.4 and earlier
IncrementalTaskInputs type is deprecated
The IncrementalTaskInputs type was used to implement incremental tasks, that is to say tasks that can be optimized to run on a subset of changed inputs instead of the whole input. This type had a number of drawbacks. In particular using this type it was not possible to determine what input a change was associated with.
You should now use the InputChanges type instead. Please refer to the userguide section about implementing incremental tasks for more details.
Potential breaking changes
Version catalog only accepts a single TOML import file
Only a single file will be accepted when using a from import method. This means that notations, which resolve to multiple files (e.g. the Project.files(java.lang.Object…) method, when more then one file is passed) will result in a build failure.
Updates to default tool integration versions
Checkstyle has been updated to Checkstyle 8.45.1.
JaCoCo has been updated to 0.8.8.
Classpath file generated by the eclipse plugin has changed
Project dependencies defined in test configurations get the test=true classpath attribute. All source sets and dependencies defined by the JVM Test Suite plugin are also marked as test code by default. You can now customize test source sets and dependencies via the eclipse plugin DSL:
Alternatively, you can adjust or remove classpath attributes in the eclipse.classpath.file.whenMerged < >block.
Signing plugin defaults to gpg instead of gpg2 when using the GPG command
In order to set the old default, the executable can be manually defined in gradle.properties :
mustRunAfter constraints no longer violated by finalizedBy dependencies
In previous Gradle versions, mustRunAfter constraints between regular tasks and finalizer task dependencies would not be honored.
For a concrete example, consider the following task graph definition:
The relevant constraints are:
dockerStop is a finalizer of dockerTest so it must be run after dockerTest ;
removeContainer is a dependency of dockerStop so it must be run before dockerStop ;
createContainer must run after removeContainer ;
Prior to Gradle 7.5, gradle dockerTest would yield the following order of execution, in violation of the mustRunAfter constraint between :createContainer and :removeContainer :
Starting with Gradle 7.5, mustRunAfter constraints are fully honored yielding the following order of execution:
Updates to bundled Gradle dependencies
Groovy has been updated to Groovy 3.0.10.
Scala Zinc version updated to 1.6.1
Zinc is the Scala incremental compiler that allows Gradle to always compile the minimal set of files needed by the current file changes. It takes into account which methods are being used and which have changed, which means it’s much more granular than just interfile dependencies.
Zinc version has been updated to the newest available one in order to benefit from all the recent bugfixes. Due to that, if you use zincVersion setting it’s advised to remove it and only use the default version, because Gradle will only be able to compile Scala code with Zinc versions set to 1.6.x or higher.
These implicit arguments have been removed and are no longer added by default. If your code or any of your dependencies are performing deep refection into JDK internals during test execution, you may see the following behavior changes:
Before Java 16, new build warnings are shown. These new warnings are printed to stderr and will not fail the build:
With Java 16 or higher, exceptions are thrown that fail the build:
If you are using TestNG, versions prior to 5.14.6 perform illegal reflection. Updating to at least 5.14.6 should fix the incompatibility.
Checkstyle tasks use toolchains and execute in parallel by default
The Checkstyle plugin now uses the Gradle worker API to run Checkstyle as an external worker process, so that multiple Checkstyle tasks may now run in parallel within a project.
Since Checkstyle runs as an external process you can control the memory via the minHeapSize and maxHeapSize properties on the Checkstyle tasks. In case of out of memory errors, increasing the max memory via the maxHeapSize property should solve the issue. By default, the process will start with maxHeapSize of 512MB. We also recommend to update Checkstyle to version 9.3 or later.
Missing files specified with relative paths when running Checkstyle
Previously, the current working directory would depend on how Gradle was executed. When running Gradle from the root directory of a project, this would be the root directory, but when running Gradle from a subproject, the current working directory would be the subproject directory.
Deprecations
Converting files to a classpath where paths contain file separator
Java has the concept of a path separator which is used to separate individual paths in a list of paths, for example in a classpath string. The individual paths must not contain the path separator. Consequently, using @FileCollection.getAsPath() for files with paths that contain a path separator has been deprecated, and it will be an error in Gradle 8.0 and later. Using a file collection with paths which contain a path separator may lead to incorrect builds, since Gradle doesn’t find the files as inputs, or even to build failures when the path containing the path separator is illegal on the operating system.
Groovydoc includePrivate property is deprecated
There is a new access property that allows finer control over what is included in the Groovydoc.
Provider-based API must be used to run external processes at the configuration time
Upgrading from 7.3 and earlier
Potential breaking changes
Updates to default tool integration versions
PMD has been updated to PMD 6.39.0.
Deprecations
AdoptOpenJDK toolchain download
Following the move from AdoptOpenJDK to Adoptium, under the Eclipse foundation, it is no longer possible to download an AdoptOpenJDK build from their end point. Instead, an Eclipse Temurin or IBM Semeru build is returned.
Gradle 7.4+ will now emit a deprecation warning when the AdoptOpenJDK vendor is specified in the toolchain specification and it is used by auto provisioning. If you must use AdoptOpenJDK, you should turn off auto-download. If an Eclipse Temurin or IBM Semeru build works for you, specify JvmVendorSpec.ADOPTIUM or JvmVendorSpec.IBM_SEMERU as the vendor or leave the vendor unspecified.
File trees and empty directory handling
When using @SkipWhenEmpty on an input file collection, Gradle skips the task when it determines that the input is empty. If the input file collection consists only of file trees, Gradle ignores directories for the emptiness check. Though when checking for changes to the input file collection, Gradle only ignores directories when the @IgnoreEmptyDirectories annotation is present.
Using LazyPublishArtifact without a FileResolver is deprecated
When using a LazyPublishArtifact without a FileResolver, a different file resolution strategy is used, which duplicates some logic in the FileResolver. To improve consistency, LazyPublishArtifact should be used with a FileResolver, and will require it in the future.
This also affects other internal APIs that use LazyPublishArtifact, which now also have deprecation warnings where needed.
TAR trees from resources without backing files
Unique attribute sets
The set of Attributes associated with a consumable configuration within a project, must be unique across all other configurations within that project _which share the same set of Capabilitys. This will be checked at the end of configuring variant configurations, as they are locked against further mutation.
If the set of attributes is shared across configurations, consider adding an additional attribute to one of the variants for the sole purpose of disambiguation.
Provider#forUseAtConfigurationTime() has been deprecated
Provider#forUseAtConfigurationTime is now deprecated and scheduled for removal in Gradle 9.0. Clients should simply remove the call.
The call was mandatory on providers of external values such as system properties, environment variables, Gradle properties and file contents meant to be used at configuration time together with the configuration cache feature.
Starting with version 7.4 Gradle will implicitly treat an external value used at configuration time as a configuration cache input.
Clients are also free to use standard Java APIs such as System#getenv to read environment variables, System#getProperty to read system properties as well as Gradle APIs such as Project#property(String) and Project#findProperty(String) to read Gradle properties at configuration time. The Provider based APIs are still the recommended way to connect external values to task inputs for maximum configuration cache reuse.
ConfigurableReport#setDestination(org.gradle.api.provider.Provider ) has been deprecated
Task execution listeners and events
The Gradle configuration cache does not support listeners and events that have direct access to Task and Project instances, which allows Gradle to execute tasks in parallel and to store the minimal amount of data in the configuration cache. In order to move towards an API that is consistent whether the configuration cache is enabled or not, the following APIs are deprecated and will be removed or be made an error in Gradle 8.0:
Registering TaskExecutionListener, TaskActionListener, TestListener, TestOutputListener via Gradle.addListener()
See the configuration cache chapter for details on how to migrate these usages to APIs that are supported by the configuration cache.
Build finished events
Build finished listeners are not supported by the Gradle configuration cache. And so, the following API are deprecated and will be removed in Gradle 8.0:
See the configuration cache chapter for details on how to migrate these usages to APIs that are supported by the configuration cache.
Calling Task#getProject() from a task action
Calling Task.getProject() from a task action at execution time is now deprecated and will be made an error in Gradle 8.0. This method can be used during configuration time, but it is recommended to avoid doing this.
See the configuration cache chapter for details on how to migrate these usages to APIs that are supported by the configuration cache.
Calling Task#getTaskDependencies() from a task action
Calling Task.getTaskDependencies() from a task action at execution time is now deprecated and will be made an error in Gradle 8.0. This method can be used during configuration time, but it is recommended to avoid doing this.
See the configuration cache chapter for details on how to migrate these usages to APIs that are supported by the configuration cache.
Using a build service from a task without the corresponding Task#usesService declaration
Gradle needs the information so it can properly honor the build service lifecycle and its usage constraints.
This will become an error in a future Gradle version.
VersionCatalog and VersionCatalogBuilder deprecations
Some methods in VersionCatalog and VersionCatalogBuilder are now deprecated and scheduled for removal in Gradle 8.0. Specific replacements can be found in the JavaDoc of the affected methods.
These methods were changed to improve the consistency between the libs.versions.toml file and the API classes.
Upgrading from 7.2 and earlier
Potential breaking changes
Updates to bundled Gradle dependencies
Kotlin has been updated to Kotlin 1.5.31.
Groovy has been updated to Groovy 3.0.9.
Application order of plugins in the plugins block
The order in which plugins in the plugins block were actually applied was inconsistent and depended on how a plugin was added to the class path. Now the plugins are always applied in the same order they are declared in the plugins block which in rare cases might change behavior of existing builds.
Effects of exclusion on substituted dependencies in dependency resolution
Prior to this version, a dependency substitution target could not be excluded from a dependency graph. This was caused by checking for exclusions prior to performing the substitution. Now Gradle will also check for exclusion on the substitution result.
Version catalog
Generated accessors no longer give access to the type unsafe API. You have to use the version catalog extension instead.
Toolchain support in Scala
Declaring input or output directories which contain unreadable content
For up-to-date checks Gradle relies on tracking the state of the inputs and the outputs of a task. Gradle used to ignore unreadable files in the input or outputs to support certain use-cases, although it cannot track their state. Declaring input or output directories on tasks which contain unreadable content has been deprecated and these use-cases are now supported by declaring the task to be untracked. Use the @UntrackedTask annotation or the Task.doNotTrackState() method to declare a task as untracked.
When you are using a Copy task for copying single files into a directory which contains unreadable files, use the method Task.doNotTrackState().
Upgrading from 7.1 and earlier
Potential breaking changes
Security changes to application start scripts and Gradle wrapper scripts
You can use the latest version of Gradle to generate a gradlew script and use it to execute an older version of Gradle.
This should be a transparent for most users; however, there may be changes for Gradle builds that rely on the environment variables JAVA_OPTS or GRADLE_OPTS to pass parameters with complicated quote escaping. Contact us if you suspect something has broken your build and you cannot find a solution.
Updates to bundled Gradle dependencies
Groovy has been updated to Groovy 3.0.8.
Kotlin has been updated to Kotlin 1.5.21.
Updates to default tool integration versions
PMD has been updated to PMD 6.36.0.
Deprecations
Using Java lambdas as task actions
When using a Java lambda to implement a task action, Gradle cannot track the implementation and the task will never be up-to-date of from the build cache. Since it is easy to add such a task action, using task actions implemented by Java lambdas is now deprecated. See Validation problems for more details how to fix the issue.
Relying on equals for up-to-date checks is deprecated
When a task input is annotated with @Input and is not a type Gradle understand directly (like String ), then Gradle uses the serialized form of the input for up-to-date checks and the build cache key. Historically, Gradle also loads the serialized value from the last execution and then uses equals() to compare it to the current value for up-to-date checks. Doing so is error prone, doesn’t work with the build cache and has a performance impact, therefore it has been deprecated. Instead of using at @Input on a type Gradle doesn’t understand directly, use @Nested and annotate the properties of the type accordingly.
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:
This is so that you can see any deprecation warnings that apply to your build.
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.
Try to run the project and debug any errors using the Troubleshooting Guide.
Upgrading from 6.8
Changes in the IDE integration
Changes in the IDEA model
The getGeneratedSourceDirectories() and getGeneratedTestDirectories() methods are removed from the IdeaContentRoot interface. Clients should replace these invocations with getSourceDirectories() and getTestDirectories() and use the isGenerated() method on the returned instances.
Dependency locking now defaults to a single file per project
The format of the dependency lockfile has been changed and as a consequence there is only one file per project instead of one file per configuration per project. This change only affects writing lock files. Gradle remains capable of loading lock state saved in the older format.
Head over to the documentation to learn how to migrate to the new format. The migration can be performed per configuration and does not have to be done in a single step. Gradle will automatically clean up previous lock files when migrating them over to the new file format.
Gradle Module Metadata is now reproducible by default
The buildId field will not be populated by default to ensure that the produced metadata file remains unchanged when no build inputs are changed. Users can still opt in to have this unique identifier part of the produced metadata if they want to, see the documentation.
The jcenter() convenience method is now deprecated
JFrog announced the sunset of the JCenter repository in February 2021. Many Gradle builds rely on JCenter for project dependencies.
Gradle emits a deprecation warning when jcenter() is used as a repository and this method is scheduled to be removed in Gradle 8.0.
Potential breaking changes
Updates to bundled Gradle dependencies
Kotlin has been updated to Kotlin 1.4.31.
Groovy has been updated to Groovy 3.0.7.
Changes to Groovy and Groovy DSL
Due to the update to the next major version of Groovy, you may experience minor issues when upgrading to Gradle 7.0.
The new version of Groovy has a stricter parser that fails to compile code that may have been accepted in previous Groovy versions. If you encounter syntax errors, check the Groovy issue tracker and Groovy 3 release highlights.
Some very specific regressions have already been fixed in the next minor version of Groovy.
Groovy modularization
Gradle no longer embeds a copy of groovy-all that bundles all Groovy modules into a single jar—only the most important modules are distributed in the Gradle distribution.
The localGroovy() dependency will include these Groovy modules:
But the following Groovy modules are not included:
You can pull these dependencies into your build like any other external dependency.
Building Gradle plugins with Groovy 3
| If you use Spock to test your plugins, you will need to use Spock 2.x. There are no compatible versions of Spock 1.x and Groovy 3. |
Performance
Depending on the number of subprojects and Groovy DSL build scripts, you may notice a performance regression when compiling build scripts for the first time or when changes are made to the build script’s classpath. This is due to the slower performance of the Groovy 3 parser, but the Groovy team is aware of the issue and trying to mitigate the regression.
In general, we are also looking at how we can improve the performance of build script compilation for both Groovy DSL and Kotlin DSL.
Encountering ‘Could not find method X for arguments Y on DefaultDependencyHandler’
While the following error initially looks like a compile error, it is actually due to the fact that specific `Configuration`s have been removed. Please refer to Removal of compile and runtime configurations for more details.
Updates to default tool integration versions
PMD has been updated to PMD 6.31.0.
Groovy and GroovyDoc have been updated to Groovy 3.0.7.
Removal of compile and runtime configurations
Since its inception, Gradle provided the compile and runtime configurations to declare dependencies. These however did not support a fine grained scoping of dependencies. Hence, better replacements were introduced in Gradle 3.4:
The implementation configuration should be used to declare dependencies which are implementation details of a library: they are not visible to consumers of the library during compilation time.
The api configuration, available only if you apply the java-library plugin, should be used to declare dependencies which are part of the API of a library, that need to be exposed to consumers at compilation time.
In Gradle 7, both the compile and runtime configurations are removed. Therefore, you have to migrate to the implementation and api configurations above. If you are still using the java plugin for a Java library, you will need to apply the java-library plugin instead.