Gradle Release Notes

Version 4.1

The Gradle team is pleased to announce the release of Gradle 4.1.

First and foremost, we are excited to announce the new Worker API for Gradle plugins, which facilitates safe parallel execution. We encourage plugin authors to read the new user guide section and implement tasks using this API because it provides parallel execution by default. Core plugins will adopt this API in future releases. Furthermore, the Gradle plugin for Android 3.0 alpha has already adopted this API, so plugin developers will be in good company. More details are given below.

This release supports running Gradle on the most recent JDK 9 release (b170+). Read our guide to building Java 9 modules to learn how to produce and consume Java 9 modules with Gradle.

Steady progress has been made to make the build cache more user-friendly. Remote build cache results are mirrored locally and build cache resolution failures no longer fail the build.

Included in this release, Gradle Kotlin DSL v0.10.3 comes with the latest Kotlin release (1.1.3), a new kotlin-dsl plugin for Gradle Plugins written in Kotlin, plus many improvements to usability, stability, and performance.

We've also spent some time making composite builds work more like multi-project builds. Included builds are now executed in parallel by default and Gradle avoids executing included build tasks multiple times when possible. Finally, you can now use --continuous build and composite builds together.

Scala enthusiasts rejoice! Scala compile and Scaladoc tasks now support Gradle's build cache. Zinc has been also upgraded to v0.3.15, which has preliminary support for compiling Scala using Java 9.

Finally, the CLI now shows more detail about tests in-progress, showing which tests are running in parallel.

Parallel Test Execution

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

Table Of Contents

New and noteworthy

Here are the new features introduced in this Gradle release.

Worker API for safe, concurrent work execution

Gradle 4.1 introduces the Worker API, a new API for safe, parallel, and asynchronous execution of units of work within a build. This API allows for:

This API can be used within a custom task class to break up the work of the task and execute that work in parallel. Once a task has submitted all of its work to run asynchronously, and has exited the task action, Gradle can then start running other independent tasks in parallel - even if those tasks are in the same project. This allows Gradle to make maximum use of the resources available and complete builds faster than ever.

source.files.each { file ->
    // Create and submit a unit of work for each file
    workerExecutor.submit(UnitOfWork.class) { config ->
        config.isolationMode = IsolationMode.NONE
        // Constructor parameters for the unit of work implementation
        config.params = [ file, project.file("${outputDir}/${file.name}") ]
    }
}

To learn more about the Worker API, check out the user guide or watch the presentation from the 2017 Gradle Summit.

Build cache improvements

Scala toolchain is now cacheable

Tasks of type ScalaCompile and ScalaDoc provided by the scala plugin are now cacheable. This means they will make use of the build cache when activated.

Remote results are mirrored locally

Given both a local and a remote cache, whenever a cached result is found remotely, it is also stored in the local cache. This way the next time the same result can be served from the local cache, without having to download it again.

Build cache errors don't fail the build

Errors like a broken HTTP connection, or corrupted data being downloaded do not fail the build anymore. Instead, the build cache is disabled for the duration of the current build.

Improved Composite Builds

Included builds now executed in parallel

Where possible, Gradle will now execute multiple included builds in parallel, by default. This parallelism is safe because of the independent nature of included builds.

The max-workers setting of the build invocation is honored for all builds within a composite: this value defines the maximum number of tasks that will run in parallel.

Continuous build now works with composite builds

Gradle's continuous build feature now works with composite builds. Gradle will automatically detect changes to any input from any build and rebuild the appropriate pieces.

Included builds executed once

In previous versions of Gradle, an included build may have been executed multiple times in order to construct multiple dependent artifacts. This occurred for compileOnly artifact dependencies, and for implementation dependencies of a java-library project. Gradle now does more work to determine these dependencies up-front, so that in almost every case and included build will only be configured and executed a single time per build invocation. The exception to this is where an included build provides multiple different artifacts, and one of these artifacts is required prior to task execution: either to provide a plugin implementation, or to satisfy a dependency resolved at configuration time.

Console displays parallel test execution

With this release of Gradle, the console displays any test worker processes executed in parallel in the work in-progress area. Each test executor line indicates the test class it is currently working on. At the moment only JVM-based test worker processes supported by Gradle core (that is JUnit and TestNG) are rendered in parallel in the console. The display of the overall test count of a Test task stays unchanged.

<========-----> 69% EXECUTING [23s]
> IDLE
> :plugin:functionalTest > 127 completed, 2 skipped
> :other:compileJava
> :plugin:functionalTest > Executing test org.gradle.plugin.ConsoleFunctionalTest
> :fooBarBazQuux:test > 3 completed
> :plugin:functionalTest > Executing test org.gradle.plugin.UiLayerFunctionalTest
> IDLE
> :fooBarBazQuux:test > Executing test org.gradle.MyTest

Faster Gradle startup

The Gradle command line client now starts up ~200ms faster, speeding up every build.

CodeNarc plugin supports report format 'console'

The CodeNarc plugin now supports outputting reports directly to the console through the console report format.

codenarc { reportFormat = 'console' }

APIs to define calculated task input and output locations

This release builds on the Provider concept added in Gradle 4.0 to add conveniences that allow plugins and build scripts to define task input and output locations that are calculated lazily. For example, a common problem when implementing a plugin is how to define task output locations relative to the project's build directory in a way that deals with changes to the build directory location later during project configuration.

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

There are no promoted features in this release.

Fixed issues

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 5.0). See the User guide 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.

Scaladoc stylesheet deprecated

The ScalaDocOptions.styleSheet property has been deprecated. The current (Scala 2.11.8 and later) Scaladoc Ant task does not support this property any more.

Using JSR-305 nullable annotation

The org.gradle.api.Nullable annotation has been deprecated, and replaced with javax.annotation.Nullable.

Deprecated public API

Potential breaking changes

Changes to handling of project dependencies from a project that does not use the Java plugin to a project that does

When a project that does not use the Java plugin has a project dependency on a project that uses the Java plugin, either directly or indirectly via another plugin, then the runtimeElements configuration of the target project will be selected. Previous versions of Gradle would select the default configuration in this case.

Previous versions of Gradle would select the runtimeElements when both projects are using the Java plugin.

This change makes the selection behaviour consistent so that the runtimeElements configuration is selected regardless of whether the consuming project uses the Java plugin or not. This is also consistent with the selection when the consuming project is using one of the Android plugins.

Default Zinc compiler upgraded from 0.3.13 to 0.3.15

This will take advantage of performance optimizations and Java 9 compatibility improvements in the latest Zinc release.

Filters defined via command line option --tests never override filters from build script

The --tests filters are now always applied on top of the filtering defined in build scripts. In previous Gradle versions, filters defined through filter.includeTestsMatching or filter.includePatterns were overridden, while other filters were not. The Test filtering documentation was adjusted to reflect the new behavior.

Changes to the Kotlin DSL

The base package has been renamed from org.gradle.script.lang.kotlin to org.gradle.kotlin.dsl so any explicit imports need to be updated after upgrading.

External contributions

We would like to thank the following community members for making contributions to this release of Gradle.

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

Known issues

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