Gradle Release Notes

Version 5.3.1

The Gradle team is excited to announce Gradle 5.3.1.

This release features support for publishing and consuming Gradle Module Metadata, feature variants or "optional dependencies", type-safe accessors in Kotlin precompiled script plugins, and more.

We would like to thank the following community contributors to this release of Gradle:

Stefan M., Evgeny Mandrikov, Simon Legner, Raman Gupta, Florian Dreier, Kenzie Togami, Ricardo Pereira, Thad House, Joe Kutner, James Nelson, and Josh Soref.

Table Of Contents

Upgrade Instructions

Switch your build to use Gradle 5.3.1 by updating your wrapper:

./gradlew wrapper --gradle-version=5.3.1

Please use the latest patch release. Gradle 5.3 has had one patch release.

Feature variants (similar to optional dependencies in Maven)

Often a library needs to express that some dependencies are only required if you use a specific feature of the library. Those dependencies must not be there unless you use that feature and therefore are often flagged as "optional" in Maven. For example, you should only get the mysql dependencies if you actually plan to use MySQL. Gradle now provides a powerful model for declaring those features a library provides, known as feature variants.

A consumer which depends on this specific feature (MySQL) of your library would then just have to tell that it needs it:

dependencies {
    // At compile time, we need the library
    implementation('org.gradle.demo:my-lib:1.0')
    
    runtimeOnly('org.gradle.demo:my-lib:1.0') {
        capabilities {
            // at runtime, we need the "MySQL" capability of this library
            requireCapability("org.gradle.demo:producer-mysql-support")
        }
    }
}

The library author can therefore model dependencies in "groups" that correspond to a feature:

java {
   // declare an "optional feature"
   registerFeature("mysqlSupport") {
       usingSourceSet(sourceSets.main)
   }
}
dependencies {
   // declare dependencies specific to the "optional feature"
   mysqlSupportImplementation "mysql:mysql-connector-java:8.0.14"
}

Long story short, this can be used to model the long requested optional dependencies! In practice, there are no optional dependencies: only dependencies that are required if you use some features of a library.

Kotlin DSL

Kotlin 1.3.21

The embedded Kotlin version has been upgraded to Kotlin 1.3.21.

Please see the Kotlin 1.3.21 announcement for details.

Type-safe accessors in precompiled script plugins

Starting with Gradle 5.3.1, Kotlin precompiled project script plugins now have type-safe accessors, just like regular project build scripts.

For example, here is how an hypothetical plugin that sets up a Java project according to some convention would be written as a Kotlin precompiled project script plugin in buildSrc:

// buildSrc/src/main/kotlin/my-java-convention.gradle.kts
plugins {
    `java-library`
    checkstyle
}

java {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

tasks {
    withType<JavaCompile> {
        options.isWarnings = true
    }
    checkstyleMain {
        maxWarnings = 0
    }
}

dependencies {
    testImplementation("junit:junit:4.12")
}

It makes use of type-safe accessors for the java {} extension, the checkstyleMain task and the testImplementation configuration, all contributed by the plugins it applies (java-library and checkstyle).

This plugin can then be applied to regular projects:

// build.gradle.kts
plugins {
    `my-java-convention`
}

See the Precompiled script plugins section of the user manual for more information.

Better help message on delete operation failure

The clean task, all Delete tasks, and project.delete {} operations now provide a better help message when failing to delete files. The most frequent and hard to troubleshoot causes for failing to delete files are other processes holding file descriptors open, and concurrent writes.

The help message now displays each failed path, which may be helpful in identifying which process might be holding files open, and will also display any files that were created in the target directory after a delete failure, which may be helpful in identifying when a process is still writing to the directory.

For example, a process holding some.file open in your build directory while running the :clean task would cause the following message to be displayed:

* What went wrong:
Execution failed for task ':clean'.
> Unable to delete directory '/path/to/your/gradle-project/build'
    Failed to delete some children. This might happen because a process has files open or has its working directory set in the target directory.
    - /path/to/your/gradle-build/subproject/build/some.file

A process still writing to your build directory while running the :clean task would display:

* What went wrong:
Execution failed for task ':clean'.
> Unable to delete directory '/path/to/your/gradle-project/build'
    New files were found. This might happen because a process is still writing to the target directory.
    - /path/to/your/gradle-build/subproject/build/new.file

Improvements for plugin authors

Public API for publishing custom components

Gradle now offers a public API to publish custom software components. Refer to the SoftwareComponentFactory documentation for details or look at the JavaPlugin and JavaPlaftormPlugin which have been migrated to use this API.

Gradle Module Metadata 1.0

Gradle Module Metadata is now 1.0.

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. You can read more about Gradle Module Metadata in this blog post.

Gradle will automatically consume published Gradle Metadata, but to publish Gradle Metadata requires you to enable the GRADLE_METADATA feature preview.

Factory method for creating ConfigurableFileCollection instances using ObjectFactory

Plugin and task implementations often need to create instances of various useful types, to provide a configurable model and DSL that is consistent with other Gradle plugins. One such type is ConfigurableFileCollection. In previous releases, plugins could use Project.files() or ProjectLayout.configurableFiles() to create instance of this type. However, these interfaces are not always available, for example in a Settings plugin (rather than a Project plugin) or in a nested model object.

In this release, plugin authors can use the ObjectFactory.fileCollection() method to create instances. The ObjectFactory service is used by plugin and task implementations to create objects of various useful types. This now includes instances of ConfigurableFileCollection.

Default JaCoCo version upgraded to 0.8.3

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

Default Checkstyle version upgraded to 8.17

The Checkstyle plugin has been upgraded to use Checkstyle version 8.17 by default.

Promoted features are features that were incubating in previous versions of Gradle but are now supported and subject to backwards compatibility. See the User Manual section on the “Feature Lifecycle” for more information.

The following are the features that have been promoted in this Gradle release.

Fixed issues

Known issues

Known issues are problems that were discovered post release that are directly related to changes made in this release.

Deprecations

Features that have become superseded or irrelevant due to the natural evolution of Gradle become deprecated, and scheduled to be removed in the next major Gradle version (Gradle 6.0). See the User Manual section on the “Feature Lifecycle” for more information.

The following are the newly deprecated items in this Gradle release. If you have concerns about a deprecation, please raise it via the Gradle Forums.

Incubating method ProjectLayout.configurableFiles() replaced by ObjectFactory.fileCollection()

The method ProjectLayout.configurableFiles() is now deprecated, and will be removed in Gradle 6.0. You should use ObjectFactory.fileCollection() instead.

Breaking changes

See the Gradle 5.x upgrade guide to learn about breaking changes and considerations when upgrading to Gradle 5.3.1.

External contributions

We love getting contributions from the Gradle community. For information on contributing, please see gradle.org/contribute.

Reporting Problems

If you find a problem with this release, please file a bug on GitHub Issues adhering to our issue guidelines. If you're not sure you're encountering a bug, please use the forum.

We hope you will build happiness with Gradle, and we look forward to your feedback via Twitter or on GitHub.