Gradle User Manual: Version 8.1.1

Unzip the distribution zip file in the directory of your choosing, e.g.:

Create a new directory C:\Gradle with File Explorer.

Open a second File Explorer window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content. Drag the content folder gradle-8.1.1 to your newly created C:\Gradle folder.

Alternatively, you can unpack the Gradle distribution ZIP into C:\Gradle using an archiver tool of your choice.

Configure your PATH environment variable to include the bin directory of the unzipped distribution, e.g.:

Alternatively, you could also add the environment variable GRADLE_HOME and point this to the unzipped distribution. Instead of adding a specific version of Gradle to your PATH, you can add $GRADLE_HOME/bin to your PATH. When upgrading to a different version of Gradle, just change the GRADLE_HOME environment variable.

In File Explorer right-click on the This PC (or Computer) icon, then click Properties → Advanced System Settings → Environmental Variables.

Under System Variables select Path, then click Edit. Add an entry for C:\Gradle\gradle-8.1.1\bin. Click OK to save.

Alternatively, you could also add the environment variable GRADLE_HOME and point this to the unzipped distribution. Instead of adding a specific version of Gradle to your Path, you can add %GRADLE_HOME%/bin to your Path. When upgrading to a different version of Gradle, just change the GRADLE_HOME environment variable.

↓ Proceed to next steps

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.

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.

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:

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.

You can find more details about the benefits of the new configurations and which one to use in place of compile and runtime by reading the Java Library plugin documentation.

The ProjectBuilder API is used for inspecting Gradle builds in unit tests. This API used to create temporary project files under the system temporary directory as defined by java.io.tmpdir.

The API now creates temporary project files under the Test task’s temporary directory. This path is usually under the project build directory. This may cause test failures when the test expects particular file paths.

If the test uses ProjectBuilder.withProjectDir(…​), it is unaffected.

Tests that use the TestKit API used to create temporary files under the system temporary directory as defined by java.io.tmpdir. These files were used to store copies of Gradle distributions or another test-only Gradle User Home.

TestKit tests will now create temporary files under the Test task’s temporary directory. This path is usually under the project build directory. This may cause test failures when the test expects particular file paths.

If the test uses GradleRunner.withTestKitDir(…​), it is unaffected.

The file system watching implementation on Windows adds a lock to the root project directory in order to watch for changes. This may cause errors when you try to delete the root project directory after running a build with TestKit. For example, tests that use TestKit together with JUnit’s @TempDir extension, or the TemporaryFolder rule can run into this problem. To avoid problems with these file locks, TestKit disables file system watching for builds executed on Windows via GradleRunner. If you’d like to override the default behavior, you can enable file system watching by passing --watch-fs to GradleRunner.withArguments().

The maven plugin has been removed. You should use the maven-publish plugin instead.

Please refer to the documentation of the Maven Publish plugin for more details.

The uploadArchives task was used in combination with the legacy Ivy or Maven publishing mechanisms. It has been removed in Gradle 7. You should migrate to the maven-publish or ivy-publish plugin instead.

Please refer to the documentation of the Maven Publish plugin for publishing on Maven repositories. Please refer to the documentation of the Ivy Publish plugin for publishing on Ivy repositories.

In the context of dependency version sorting, a -SNAPSHOT version is now considered to be right before a final release but after any -RC version. More special version suffixes are also taken into account. This brings the Gradle algorithm closer to the Maven one for well-known version suffixes.

Have a look at the documentation for all the rules Gradle applies.

The deprecated Play plugins have been removed. An external replacement, the Play Framework plugin, is available from the plugin portal.

The following plugins for experimental JavaScript integration are now removed from the distribution: coffeescript-base, envjs, javascript-base, jshint, rhino.

If you used these plugins despite their experimental nature, you may find suitable replacements in the Plugin Portal.

The layout method taking a configuration block has been removed and is replaced by patternLayout.

A Gradle build is defined by its settings.gradle(.kts) file found in the current or parent directory. Without a settings file, a Gradle build is undefined and Gradle produces an error when attempting to execute tasks.

To fix this error, create a settings.gradle(.kts) file for the build.

Exceptions to this are invoking Gradle with the init task or using diagnostic command line flags, such as --version.

Gradle 6.x warns users about the wrong behavior and ignores the target action in this scenario. Starting from 7.0 the same case will produce an error. Plugins and build scripts should be adjusted to call afterEvaluate only at configuration time. If you have such a build failure and the related afterEvaluate statement is declared in your build sources then you can simply delete it. If afterEvaluate is declared in a plugin then report the issue to the plugin maintainers.

Please use ObjectFactory#fileCollection() instead.

Please use the libsDirectory and distsDirectory properties instead.

Existing usages should be replaced with RuntimeException.

The getBaseName() and setBaseName() methods were removed from the Distribution class. Clients should replace the usages with the distributionBaseName property.

Registering a task with the AbstractTask type or with a type extending AbstractTask was deprecated in Gradle 6.5 and is now an error in Gradle 7.0. You can use DefaultTask instead.

BuildListener.buildStarted(Gradle) was deprecated in Gradle 6.0 and is now removed in Gradle 7.0. Please use BuildListener.beforeSettings(Settings) instead.

The following APIs, which were not usable via command line options anymore since Gradle 5.0, are now removed: StartParameter.useEmptySettings(), StartParameter.isUseEmptySettings(), StartParameter.setSearchUpwards(boolean) and StartParameter.isSearchUpwards().

Gradle no longer supports discovering the settings file in a directory named master in a sibling directory. If your build still uses this deprecated feature, consider refactoring the build to have the root directory match the physical root of the project hierarchy. You can find more information about how to structure a Gradle build or a composition of builds in the user manual. Alternatively, you can still run tasks in builds like this by invoking the build from the master directory only using a fully qualified path to the task.

Compiling, testing and executing now works automatically for any source set that defines a module by containing a module-info.java file. Usually, this is the behavior you need. If this is causing issues in cases you manually configure the module path, or use a 3rd party plugin for it, you can still opt out of this by setting modularity.inferModulePath to false on the java extension or individual tasks.

The ValidateTaskProperties task has been removed and replaced by the ValidatePlugins task.

The ImmutableFileCollection type has been removed. Use the factory method instead. A handle to the project layout can be obtained via Project.layout.

The method ComponentSelectionReason.getDescription has been removed. It is replaced by ComponentSelectionReason.getDescriptions which returns a list of ComponentSelectionDescriptor, each having a getDescription.

The following deprecated constructors were removed:

The local build cache configuration now needs to be done via BuildCacheConfiguration.local().

This internal API was used in plugins, amongst other the Nebula plugins, and was deprecated in the Gradle 5.x timeline and is now removed. Latest plugins version should no longer reference it.

The checkstyle plugin now fails for the following configuration

Builds should declare the checkstyle configuration with the checkstyle block:

Gradle 6.x warns users about the wrong behavior and then returns a possibly incorrect provider value. Starting with 7.0 the same case will produce an error. Plugins and build scripts should be adjusted to query the mapped value of a provider, for example a task output property, after the task has completed.

Gradle 6.0 started warning about problems with task definitions (such as incorrectly defined inputs or outputs). For Gradle 7.0, those warnings are now errors and will fail the build.

Previous Gradle releases had an inconsistent behavior in regard to conflict resolution in a particular configuration: - your project declares a strict dependency on a published module (for example, com.mycompany:some-module:1.2!!, where 1.2!! is the short hand notation for a strict dependency on 1.2) - your build actually provides com.mycompany:some-module in a higher version

Previous Gradle releases would succeed, selecting the project dependency despite the strict constraint. Starting from Gradle 7, this will trigger a dependency resolution failure.

See this issue for more context.

Having a task which produces an output in a location and another task consuming that location by referring to it as an input without the consumer task depending on the producer task has been deprecated. A fix for this problem is to add a dependency from the consumer to the producer.

Gradle 7 now fails when a copy operation (or any operation which uses a org.gradle.api.file.CopySpec) encounters a duplicate entry, and that the duplicates strategy isn’t set. Please look at the CopySpec docs for details.

The API supporting the Java Toolchain feature in org.gradle.jvm.toolchain is now marked as @NonNull.

This may impact Kotlin consumers where the return types of APIs are no longer nullable.

Previously, projects imported by Eclipse only included dependencies for the main and test source sets. The compile and runtime classpaths of custom source sets were ignored.

Since Gradle 6.8, projects imported into Eclipse include the compile and runtime classpath for every source set defined by the build.

Previously, empty directories would be taken into account during up-to-date checks and build cache key calculations for the sources declared in SourceTask. This meant that a source tree that contained an empty directory and an otherwise identical source tree that did not contain the empty directory would be considered different sources, even if the task would produce the same outputs. In Gradle 6.8, SourceTask now ignores empty directories during doing up-to-date checks and build cache key calculations. In the vast majority of cases, this is the desired behavior, but it is possible that a task may extend SourceTask but also produce different outputs when empty directories are present in the sources. For tasks where this is a concern, you can expose a separate property without the @IgnoreEmptyDirectories annotation in order to capture those changes:

Publishing a component which has a dependency on an enforced platform now triggers a validation error, preventing accidental publishing of bad metadata: enforced platforms use cases should be limited to applications, not things which can be consumed from another library or an application.

If, for some reason, you still want to publish components with dependencies on enforced platforms, you can disable the validation following the documentation.

Gradle’s file trees apply some default exclude patterns for convenience — the same defaults as Ant in fact. See the user manual for more information. Sometimes, Ant’s default excludes prove problematic, for example when you want to include the .gitignore in an archive file.

Changing Gradle’s default excludes during the execution phase can lead to correctness problems with up-to-date checks. As a consequence, you are only allowed to change Gradle’s default excludes in the settings script, see the user manual for an example.

Direct references to tasks from included builds in mustRunAfter, shouldRunAfter and finalizedBy task methods have been deprecated. Task ordering using mustRunAfter and shouldRunAfter as well as finalizers specified by finalizedBy should be used for task ordering within a build. If you happen to have cross-build task ordering defined using above mentioned methods, consider restructuring such builds and decoupling them from one another.

Gradle will emit a deprecation warning when your build relies on finding the settings file in a directory named master in a sibling directory.

If your build uses this feature, consider refactoring the build to have the root directory match the physical root of the project hierarchy.

Alternatively, you can still run tasks in builds like this by invoking the build from the master directory only using a fully qualified path to the task.

Gradle Kotlin DSL extensions have been changed to favor Gradle’s Action<T> type over Kotlin function types.

While the change should be transparent to Kotlin clients, Java clients calling Kotlin DSL extensions need to be updated to use the Action<T> APIs.

Previously, buildSrc was built in such a way that included builds were ignored from the root build.

Since Gradle 6.7, buildSrc can see any included build from the root build. This may cause dependencies to be substituted from an included build in buildSrc. This may also change the order in which some builds are executed if an included build is needed by buildSrc.

Gradle’s file trees apply some default exclude patterns for convenience — the same defaults as Ant in fact. See the user manual for more information. Sometimes, Ant’s default excludes prove problematic, for example when you want to include the .gitignore in an archive file.

Changing Gradle’s default excludes during the execution phase can lead to correctness problems with up-to-date checks, and is deprecated. You are only allowed to change Gradle’s default excludes in the settings script, see the user manual for an example.

Gradle allowed instances of Configuration to be used directly as dependencies:

This behavior is now deprecated as it is confusing: one could expect the "dependent configuration" to be resolved first and add the result of resolution as dependencies to the including configuration, which is not the case. The deprecated version can be replaced with the actual behavior, which is configuration inheritance:

While adding support for expressing variant support in dependency substitutions, a bug fix introduced a behaviour change that some builds may rely upon. Previously a substituted dependency would still use the attributes of the original selector instead of the ones from the replacement selector.

With that change, existing substitutions around dependencies with richer selectors, such as for platform dependencies, will no longer work as they did. It becomes mandatory to define the variant aware part in the target selector.

You can be affected by this change if you:

See the documentation for resolving issues if you are impacted.

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:

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:

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:

Users of the Groovy DSL should not be impacted as the notation lockMode = LockMode.STRICT remains valid.

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.

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.

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

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.

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.

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.

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.

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.

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:

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.

The following methods have been discontinued and should no longer be used. They will be removed in Gradle 7.0.

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.

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.

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:

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:

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:

Alternatively, you might want to re-enable the jar task, and add the bootJar with a different classifier.

The usage of the compile and runtime configurations in the Java ecosystem plugins has been discouraged since Gradle 3.4.

These configurations are used for compiling and running code from the main source set. Other sources sets create similar configurations (e.g. testCompile and testRuntime for the test source set), should not be used either. The implementation, api, compileOnly and runtimeOnly configurations should be used to declare dependencies and the compileClasspath and runtimeClasspath configurations to resolve dependencies. See the relationship of these configurations.

The uploadArchives task and the maven plugin are deprecated.

Users should migrate to the publishing system of Gradle by using either the maven-publish or ivy-publish plugins. These plugins have been stable since Gradle 4.8.

The publishing system is also the only way to ensure the publication of Gradle Module Metadata.

When Gradle detects problems with task definitions (such as incorrectly defined inputs or outputs) it will show the following message on the console:

The deprecation warnings show up in build scans for every build, regardless of the command-line switches used.

When the build is executed with --warning-mode all, the individual warnings will be shown:

If you own the code of the tasks in question, you can fix them by following the suggestions. You can also use --stacktrace to see where in the code each warning originates from.

Otherwise, you’ll need to report the problems to the maintainer of the relevant task or plugin.

In Gradle 5.4 we introduced a new API for implementing incremental tasks: InputChanges. The old API based on IncrementalTaskInputs has been deprecated.

Forcing dependency versions using force = true on a first-level dependency has been deprecated.

Force has both a semantic and ordering issue which can be avoided by using a strict version constraint.

In Gradle 5.0, we removed the --no-search-upward CLI parameter.

The related APIs in StartParameter (like isSearchUpwards()) are now deprecated.

These methods currently do not work as expected since the callbacks will never be called after the build has started.

The methods are being deprecated to avoid confusion.

Archive tasks Tar and Zip by default allow multiple entries for the same path to exist in the created archive. This can cause "grossly invalid zip files" that can trigger zip bomb detection.

To prevent this from happening accidentally, encountering duplicates while creating an archive now produces a deprecation message and will fail the build starting with Gradle 7.0.

Copy tasks also happily copy multiple sources with the same relative path to the destination directory. This behavior has also been deprecated.

If you want to allow duplicates, you can specify that explicitly:

A Gradle build is defined by a settings.gradle[.kts] file in the current or parent directory. Without a settings file, a Gradle build is undefined and will emit a deprecation warning.

In Gradle 7.0, Gradle will only allow you to invoke the init task or diagnostic command line flags, such as --version, with undefined builds.

Once a project is evaluated, Gradle ignores all configuration passed to Project#afterEvaluate and emits a deprecation warning. This scenario will become an error in Gradle 7.0.

The following bundled plugins were never announced and will be removed in the next major release of Gradle:

Some of these plugins may have replacements on the Plugin Portal.

Gradle 6.0 supports Android Gradle Plugin versions 3.4 and later.

For Gradle 6, usage of the build scan plugin must be replaced with the Gradle Enterprise plugin. This also requires changing how the plugin is applied. Please see https://gradle.com/help/gradle-6-build-scan-plugin for more information.

Previously, Gradle used the name of the root project as the build name for an included build. Now, the name of the build’s root directory is used and the root project name is not considered if different. A different name for the build can be specified if the build is being included via a settings file.

The previous behavior was problematic as it caused different names to be used at different times during the build.

Previously, Gradle did not prevent using the name “buildSrc” for a subproject of a multi-project build or as the name of an included build. Now, this is not allowed. The name “buildSrc” is now reserved for the conventional buildSrc project that builds extra build logic.

Typical use of buildSrc is unaffected by this change. You will only be affected if your settings file specifies include("buildSrc") or includeBuild("buildSrc").

The Zinc compiler has been upgraded to version 1.3.0. Gradle no longer supports building for Scala 2.9.

The minimum Zinc compiler supported by Gradle is 1.2.0 and the maximum tested version is 1.3.0.

To make it easier to select the version of the Zinc compiler, you can now configure a zincVersion property:

Please remove any explicit dependencies you’ve added to the zinc configuration and use this property instead. If you try to use the com.typesafe.zinc:zinc dependency, Gradle will switch to the new Zinc implementation.

In the past, it was possible to use any build cache implementation as the local cache. This is no longer allowed as the local cache must always be a DirectoryBuildCache.

Calls to BuildCacheConfiguration.local(Class) with anything other than DirectoryBuildCache as the type will fail the build. Calling these methods with the DirectoryBuildCache type will produce a deprecation warning.

Use getLocal() and local(Action) instead.

In the past, when Gradle encountered a problem while packing the results of a cached task, Gradle would ignore the problem and continue running the build.

When encountering a corrupt cached artifact, Gradle would remove whatever was already unpacked and re-execute the task to make sure the build had a chance to succeed.

While this behavior was intended to make a build successful, this had the adverse effect of hiding problems and led to reduced cache performance.

In Gradle 6.0, both pack and unpack errors will cause the build to fail, so that these problems will be surfaced more easily.

Previously, in order to use the build cache for the buildSrc build you needed to duplicate your build cache config in the buildSrc build. Now, it automatically uses the build cache configuration defined by the top level settings script.

Officially introduced in Gradle 5.3, Gradle Module Metadata was created to solve many of the problems that have plagued dependency management for years, in particular, but not exclusively, in the Java ecosystem.

With Gradle 6.0, Gradle Module Metadata is enabled by default.

This means, if you are publishing libraries with Gradle and using the maven-publish or ivy-publish plugin, the Gradle Module Metadata file is always published in addition to traditional metadata.

The traditional metadata file will contain a marker so that Gradle knows that there is additional metadata to consume.

The following rules are verified when publishing Gradle Module Metadata:

These are documented in the specification as well.

If Gradle fails to locate the metadata file (.pom or ivy.xml) of a module in a repository defined in the repositories { } section, it now assumes that the module does not exist in that repository.

For dynamic versions, the maven-metadata.xml for the corresponding module needs to be present in a Maven repository.

Previously, Gradle would also look for a default artifact (.jar). This behavior often caused a large number of unnecessary requests when using multiple repositories that slowed builds down.

You can opt into the old behavior for selected repositories by adding the artifact() metadata source.

Previously, if the pom packaging was not jar, ejb, bundle or maven-plugin, the extension of the main artifact published to a Maven repository was changed during publishing to match the pom packaging.

This behavior led to broken Gradle Module Metadata and was difficult to understand due to handling of different packaging types.

Build authors can change the artifact name when the artifact is created to obtain the same result as before — e.g. by setting jar.archiveExtension.set(pomPackaging) explicitly.

A number of fixes were made to produce more correct ivy.xml metadata in the ivy-publish plugin.

As a consequence, the internal structure of the ivy.xml file has changed. The runtime configuration now contains more information, which corresponds to the runtimeElements variant of a Java library. The default configuration should yield the same result as before.

In general, users are advised to migrate from ivy.xml to the new Gradle Module Metadata format.

Previously, the buildSrc project was built before applying the project’s settings script and its classes were visible within the script. Now, buildSrc is built after the settings script and its classes are not visible to it. The buildSrc classes remain visible to project build scripts and script plugins.

Custom logic can be used from a settings script by declaring external dependencies.

Previously, any pluginManagement {} blocks inside a settings script were executed during the normal execution of the script.

Now, they are executed earlier in a similar manner to buildscript {} or plugins {}. This means that code inside such a block cannot reference anything declared elsewhere in the script.

This change has been made so that pluginManagement configuration can also be applied when resolving plugins for the settings script itself.

Previously, any classes added to the a settings script by using buildscript {} were not visible outside of the script. Now, they are visible to all of the project build scripts.

They are also visible to the buildSrc build script and its settings script.

This change has been made so that plugins applied to the settings script can contribute logic to the entire build.

Just like when using the kotlin-dsl plugin, it is now required to declare a repository where Kotlin dependencies can be found if you apply the embedded-kotlin plugin.

With Kotlin IntelliJ plugin versions prior to 1.3.50, Kotlin DSL scripts will be wrongly highlighted when the Gradle JVM is set to a version different from the one in Project SDK. Simply upgrade your IDE plugin to a version >= 1.3.50 to restore the correct Kotlin DSL script highlighting behavior.

In previous versions, Kotlin DSL scripts were compiled to classes that implemented one of the three core Gradle configuration interfaces in order to implicitly expose their APIs to scripts. org.gradle.api.Project for project scripts, org.gradle.api.initialization.Settings for settings scripts and org.gradle.api.invocation.Gradle for init scripts.

Having the script instance implement the core Gradle interface of the model object it was supposed to configure was convenient because it made the model object API immediately available to the body of the script but it was also a lie that could cause all sorts of trouble whenever the script itself was used in place of the model object, a project script was not a proper Project instance just because it implemented the core Project interface and the same was true for settings and init scripts.

In 6.0 all Kotlin DSL scripts are compiled to classes that implement the newly introduced org.gradle.kotlin.dsl.KotlinScript interface and the corresponding model objects are now available as implicit receivers in the body of the scripts. In other words, a project script behaves as if the body of the script is enclosed within a with(project) { …​ } block, a settings script as if the body of the script is enclosed within a with(settings) { …​ } block and an init script as if the body of the script is enclosed within a with(gradle) { …​ } block. This implies the corresponding model object is also available as a property in the body of the script, the project property for project scripts, the settings property for settings scripts and the gradle property for init scripts.

As part of the change, the SettingsScriptApi interface is no longer implemented by settings scripts and the InitScriptApi interface is no longer implemented by init scripts. They should be replaced with the corresponding model object interfaces, Settings and Gradle.

Timestamps in the generated documentation have very limited practical use, however they make it impossible to have repeatable documentation builds. Therefore, the Javadoc and Groovydoc tasks are now configured to not include timestamps by default any more.

Gradle always uses configDirectory as the value for 'config_loc' when running Checkstyle.

In Gradle 6.0, we introduced a new progress event (org.gradle.tooling.events.test.TestOutputEvent) to expose the output of test execution. This new event breaks the convention of having a StartEvent-FinishEvent pair to express progress. TaskOutputEvent is a simple ProgressEvent.

The following deprecated methods on the task container now result in errors:

Additionally, the following deprecated functionality now results in an error:

Use ObjectFactory.fileProperty() instead of the following methods that are now removed:

Use ObjectFactory.directoryProperty() instead of the following methods that are now removed:

The org.gradle.api.Nullable annotation type has been removed. Use javax.annotation.Nullable from JSR-305 instead.

The deprecated FindBugs plugin has been removed. As an alternative, you can use the SpotBugs plugin from the Gradle Plugin Portal.

The deprecated JDepend plugin has been removed. There are a number of community-provided plugins for code and architecture analysis available on the Gradle Plugin Portal.

The deprecated OSGI plugin has been removed. There are a number of community-provided OSGI plugins available on the Gradle Plugin Portal.

The deprecated announce and build-announcements plugins have been removed. There are a number of community-provided plugins for sending out notifications available on the Gradle Plugin Portal.

The deprecated Compare Gradle Builds plugin has been removed. Please use build scans for build analysis and comparison.

The deprecated Play plugin has been removed. An external replacement, the Play Framework plugin, is available from the plugin portal.

The abstract method compile() is no longer declared by AbstractCompile.

Tasks extending AbstractCompile can implement their own @TaskAction method with the name of their choosing.

They are also free to add a method annotated with @TaskAction using an InputChanges parameter without having to implement a parameter-less one as well.

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 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 declaring outputs is now deprecated. Declare file outputs or use TaskOutputs.upToDateWhen() instead.

This will become an error in Gradle 6.0.

The WorkerExecutor.submit() method is now deprecated. The new noIsolation(), classLoaderIsolation() and processIsolation() methods should now be used to submit work. See the section on the Worker API for more information on using these methods.

WorkerExecutor.submit() will be removed in Gradle 8.0.

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.

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

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.

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_\\-.]+.

Gradle now prevents internal dependencies (like Guava) from leaking into the classpath used by Worker API actions. This fixes 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.

The PMD plugin has been upgraded to use PMD version 6.15.0 instead of 6.8.0 by default.

Contributed by wreulicke

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)

Gradle 5.6 no longer supplies custom classpath attributes in the Eclipse model. Instead, it provides the attributes for Eclipse test sources. This change requires Buildship version 3.1.1 or later.

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 blog post and 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.

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:

See the capabilities section of the documentation for more options.

When Gradle has to remove the output files of a task for various reasons, it will not follow symlinked directories. The symlink itself will be deleted, but the contents of the linked directory will stay intact.

The built-in Play plugin has been deprecated and will be replaced by a new Play Framework plugin available from the plugin portal.

The build comparison plugin has been deprecated and will be removed in the next major version of Gradle.

Build scans show much deeper insights into your build and you can use Gradle Enterprise to directly compare two build’s build-scans.

Project names configured via 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 Christian Fränkel

The JaCoCo plugin has been upgraded to use JaCoCo version 0.8.4 instead of 0.8.3 by default.

Contributed by Evgeny Mandrikov

The version of Ant distributed with Gradle has been upgraded to 1.9.14 from 1.9.13.

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

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.

The system classpath for worker daemons started by the 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.

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.

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().

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

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:

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:

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.

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.

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.

Input and output files of Sign tasks are now tracked via Signature.getToSign() and Signature.getFile(), respectively.

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.

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.

To expand our idiomatic Provider API practices, the install name property from org.gradle.nativeplatform.tasks.LinkSharedLibrary is affected by this change.

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.

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.

The incubating operatingSystems property on native components has been replaced with the targetMachines property.

The property factory methods such as newInputFile() are intended to be called from the constructor of a type that extends DefaultTask. These methods are now final to avoid subclasses overriding these methods and using state that is not initialized.

The Property instances that are returned by these methods are no longer automatically registered as inputs or outputs of the task. The Property instances need to be declared as inputs or outputs in the usual ways, such as attaching annotations such as @OutputFile or using the runtime API to register the property.

For example, you could previously use the following syntax and have both outputFile instances registered as declared outputs:

Now you have to explicitly register outputFile, like this: