Gradle 5.0 Release Notes

# Gradle Release Notes

### Version 5.0

The Gradle team is excited to announce Gradle 5.0.

This release features a production-ready Kotlin DSL, dependency version alignment (similar to and usable with Maven BOMs), task timeouts, Java 11 support, and more.

These release notes list what's new since Gradle 4.10. You can review the highlights since Gradle 4.0 here.

Read the Gradle 5.0 upgrade guide to learn about breaking changes and considerations for upgrading from Gradle 4.x.

We would like to thank the following community contributors to this release of Gradle: Jean-Baptiste Nizet, Jonathan Leitschuh, Ben McCann, Björn Kautler, Georg Friedrich, Stefan M., Xiang Li, Theodore Ni, James Justinic, Mike Kobit, Alex Saveau, Kevin Macksamie, Cliffred van Velzen, Artem Zinnatullin, Jakub Strzyżewski, Martin Dünkelmann, Thad House, Dan Sanduleac, Felipe Lima, and thc202.

## Table Of Contents

## Kotlin DSL 1.0

First and foremost, Gradle Kotlin DSL is now production-ready with it's 1.0 release! Authoring your build logic using Kotlin provides significant additional editing assistance in IDEs, including: improved completion, error highlighting, and refactoring tools. Please read our Gradle Kotlin DSL Primer and follow our migrating build logic from Groovy to Kotlin guide if you're interested. If you prefer the flexibility and dynamic features of Groovy, that's totally okay — the Groovy DSL will not be deprecated.

## Dependency version alignment

This version of Gradle introduces dependency version alignment. This allows different modules belonging to the same logical group (`platform`) to have identical versions in a dependency graph. Maven BOMs can be imported to define platforms as well.

    dependencies {
        // import a BOM. The versions used in this file will override any other version found in the graph
        implementation(enforcedPlatform("org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE"))

         // define dependencies without versions
        implementation("com.google.code.gson:gson")
        implementation("dom4j:dom4j")

         // this version will be overriden by the one found in the BOM
        implementation("org.codehaus.groovy:groovy:1.8.6")
    }

More details about BOM import can be found in this section of the userguide.

## Gradle build initialization features

`gradle init` functionality has been upgraded in this release: is now optionally interactive, includes new `kotlin-library` and `kotlin-application` project types, provides options for configuring project and package names, and more.

#### Interactive mode

If you run the `init` task from an interactive console, Gradle will prompt you for details of the Gradle build that you'd like to generate.

#### Kotlin library and applications

The `init` task can generate a Kotlin library or application, using the `kotlin-library` or `kotlin-application` setup type. This was one of our top 10 most voted issues. To try it out, just run `gradle init` and follow the prompts.

#### Generated builds use recommended configurations

The `init` task generates build scripts that use the recommended `implementation`, `testImplementation`, and `testRuntimeOnly` configurations instead of `compile`, `testCompile`, and `testRuntime`, respectively, for all build setup types.

#### Configure project and source package names

The `init` task provides a `--project-name` option to allow you to adjust the name of the generated project, and a `--package` option to allow you to adjust the package for the generated source. The task will also prompt you to configure these if you run the task interactively.

#### Create resource directories

The `init` task creates empty resource directories.

#### Create a .gitignore file

While the `init` task does not automatically create a Git repository, the `init` task generates a simple `.gitignore` file to make it easier for you to set up a Git repository. This `.gitignore` file ignores Gradle's build outputs.

## Searchable documentation

Search for Gradle Docs is back. The kind folks at Algolia kindly host an index used to allow you to search the user manual and DSL reference.

Gradle API Javadocs now take advantage of Javadoc built-in autocomplete, making it easier to find classes and methods you're interested in.

## Task timeouts

You can now specify a timeout duration for a task, after which it will be interrupted. Read more about task timeouts in the docs.

## HTTP retries during dependency resolution

When Gradle attempts to connect to a remote repository via HTTP, if it fails, Gradle will retry before blacklisting the repository.

No extra configuration is needed. See the section on HTTP retries for more information.

## Performance features

### Gradle can be started as a low-priority process

You can now use the `--priority low` command line argument or `org.gradle.priority=low` property to start Gradle as a low priority process. This ensures that other applications like your IDE or browser stay responsive, even while a very demanding build is running.

### Plural task output properties don't disable caching anymore

When using `@OutputFiles` or `@OutputDirectories` with an `Iterable` type, Gradle used to disable caching for the task with the following message:

> Declares multiple output files for the single output property 'outputFiles' via @OutputFiles, @OutputDirectories or TaskOutputs.files()

This is no longer the case, and using such properties doesn't prevent the task from being cached. The only remaining reason to disable caching for the task is if the output contains file trees.

### JaCoCo plugin now works with the build cache and parallel test execution

The JaCoCo plugin plugin now works seamlessly with the build cache. When applying the plugin with no extra configuration, the test task stays cacheable and parallel test execution can be used.

In order to make the tasks cacheable when generating execution data with `append = true`, the tasks running with code coverage are configured to delete the execution data just before they starts executing. In this way, stale execution data, which would cause non-repeatable task outputs, is removed.

Since Gradle now takes care of removing the execution data, the `JacocoPluginExtension.append` property has been deprecated. The JaCoCo agent is always configured with `append = true`, so it can be used when running tests in parallel.

## Java 11 runtime support

Java enthusiasts will be happy to read that this release supports running Gradle builds with JDK 11.

## Plugin authoring features

This release introduces useful changes for plugin and custom task authors, including an API for creating `SourceDirectorySet`s, improvements to the `Provider` API, and improved build cache compatibility.

### Public method to create SourceDirectorySet instances

The `SourceDirectorySet` type is often used by plugins to represent some set of source directories and files. Previously, it was only possible to create instances of `SourceDirectorySet` using internal Gradle types. This is problematic because when a plugin uses internal types it can often break when new versions of Gradle are released because internal types may change in breaking ways between releases.

In this release of Gradle, the `ObjectFactory` service, which is part of the public API, now includes a method to create `SourceDirectorySet` instances. Plugins can use this method instead of the internal types.

### Provider implementations track their producer task

An important feature of the `Provider` API is that `Provider` instances can track both a value and the task or tasks that produces that value. When a `Provider` that represents an output of a task is connected to a `Property` instance that represents a task input, Gradle automatically adds task dependencies between the tasks. This eliminates a class of configuration problems where the location of a task input and the producing task dependencies are not kept in sync as configuration changes are made.

In this release, more `Provider` implementations track the tasks that produces the value of the provider:

- Any provider returned by `TaskContainer`
- Any property marked with `@OutputFile`, `@OutputDirectory`, `@OutputFiles` or `@OutputDirectories`.
- Any `List` or `Set` property whose elements match these criteria.
- Any provider returned by `Provider.map()` or `flatMap()` that matches these criteria.

### Added Provider.flatMap() method

The `flatMap()` method allows you to apply a transformation to the values of an existing `Provider` without realizing the values of that `Provider`. It returns a new `Provider` object that is "live" (meaning it will reflect any changes to the values of the original `Provider`) but will return the transformed values when queried.

### Added Property.finalizeValue() method

The property types have a `finalizeValue()` method which prevents further changes to the value of the property. This is useful in cases where the property needs to be queried and it would be unsafe to then change the value of the property later. After this method as been invoked, calls to methods that change the value of the property (such as `set()`) will result in an exception.

### Task properties are made final before task executes

All task properties that use one of the property types have their value made final when the task executes. This prevents ordering issues where a task property is inadvertently changed after the task executes, resulting in the change having no effect. This will now result in an exception, alerting the user to the unintended error.

### Changes to file and directory property construction

`ObjectFactory` is now used to create file and directory `Property` instances, similar to other `Property` types. Previously, this was done using either the methods on `DefaultTask`, which was available only for `DefaultTask` subclasses, or using `ProjectLayout`, only available for projects. Now a single type `ObjectFactory` can be used to create all property instances in a Gradle model object.

These other methods have been deprecated and will be removed in Gradle 6.0.

## Gradle Native features

The Gradle Native project continues to improve and evolve the native ecosystem support for Gradle.

## Promoted features

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.

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

### Some long existing incubating features have been promoted

- all pre 4.0 incubating APIs have been promoted
- parallel task execution
- continuous build
- composite build
- the `java-gradle-plugin` plugin
- the `distribution` plugin
- the `jacoco` plugin
- the `build-init` plugin
- `IncrementalTaskInputs` and `InputFileDetails`
- input normalization (`org.gradle.normalization`) including `InputNormalizationHandler`
- `FileNormalizer` and its subclasses
- `@LocalState`, `Task.getLocalState()` and `TaskLocalState`
- `Task.getDestroyables()`
- `TaskState.getUpToDate()` and `TaskState.getNoSource()`
- the `ValidateTaskProperties` task
- `AbstractArchiveTask.preserveFileTimestamps` and `reproducibleFileOrder` properties
- `ForkOptions.javaHome` property
- `Project.normalization`
- `GroovyCompile.groovyCompilerJvmVersion` and `javaToolChain` properties
- `JavaVersion.VERSION_11` constant along with `isJava11()` and `isJava11Compatible()` methods

### The `--no-rebuild` option is no longer deprecated

A change in `buildSrc` causes the whole project to become out-of-date. Thus, when making small incremental changes, the `--no-rebuild` command-line option is often helpful to get faster feedback and is therefore no longer deprecated.

## Fixed issues

## Known issues

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

### Reporting of TestNG classes/methods

When using a recent version of TestNG (6.9.13.3 or newer), classes were reported to `TestListeners` as sibling `TestDescriptors` of test method `TestDescriptors`. Now, `TestDescriptors` of classes are parents of their enclosing method `TestDescriptors`.

## Potential breaking changes

This is a new major version of Gradle, so many of the things that were deprecated in the Gradle 4.x versions have been removed. For examples, there have been fixes to dependency resolution that break corner cases, and running Gradle now requires Java 8 or higher (though tests can be run using Java 6 or 7). Breaking changes are listed with detailed explanations in upgrading Gradle 4.x.

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

### StartParameter properties

The following properties are deprecated and will be removed in Gradle 6.0.

- `interactive`
- `recompileScripts`

### Removing tasks from TaskContainer

Removing tasks from the `TaskContainer` using the following methods has been deprecated and will be an error in Gradle 6.0.

- `remove(Object)`
- `removeAll(Collection)`
- `retainAll(Collection)`
- `clear()`
- `Iterator#remove()` via `TaskContainer#iterator()`

With the deprecation of every method for removing a task, registering a callback when an object is removed is also deprecated (`whenObjectRemoved(Closure/Action)`). These methods will be removed in Gradle 6.0

### Replacing tasks

It is only safe to replace an unrealized tasks registered with the new Task API because this task has not been used by anything else.

In Gradle 6.0, these behaviors will be treated as errors.

#### Replacing tasks that may still be used by other tasks

Gradle now emits a deprecation warning when you attempt to replace a task that may have already been used by something else.

#### Replacing tasks with a task of an incompatible type

Gradle now emits a deprecation warning when you attempt to replace a task with a type that's incompatible from the task being replaced.

#### Replacing a task that does not exist

Gradle now emits a deprecation warning when you attempt to replace a task that does not already exist.

### Removing dependencies from a task

In the next major release (6.0), removing dependencies from a task will become an error.

Gradle will emit a deprecation warning for code such as `foo.dependsOn.remove(bar)`. Removing dependencies in this way is error-prone and relies on the internal implementation details of how different tasks are wired together. At the moment, we are not planning to provide an alternative. In most cases, task dependencies should be expressed via task inputs instead of explicit `dependsOn` relationships.

### Changes to incubating factory methods for creating properties

The following deprecated methods have been removed:

- `ProjectLayout.newDirectoryVar()` - Use `ObjectFactory.directoryProperty()` instead.
- `ProjectLayout.newFileVar()` - Use `ObjectFactory. fileProperty()` instead.

The following methods have been deprecated and will be removed in Gradle 6.0:

- `DefaultTask.newOutputDirectory()` - Use `ObjectFactory.directoryProperty()` instead.
- `DefaultTask.newOutputFile()` - Use `ObjectFactory.fileProperty()` instead.
- `DefaultTask.newInputDirectory()` - Use `ObjectFactory.directoryProperty()` instead.
- `DefaultTask.newInputFile()` - Use `ObjectFactory.fileProperty()` instead.
- `ProjectLayout.directoryProperty()` - Use `ObjectFactory.directoryProperty()` instead.
- `ProjectLayout.fileProperty()` - Use `ObjectFactory.fileProperty()` instead.

### Initial value for `Property` types

The `ObjectFactory.property(type)`, `listProperty(type)` and `setProperty(type)` methods no longer set an initial value for the property. Instead, you can use the `value()` method (or any other mutation method) to set an initial value, if required.

For `ListProperty` and `SetProperty`, you can use `empty()` to initialize the property to an empty collection.

### The property `append` on `JacocoTaskExtension` has been deprecated

See above for details.

### The property `effectiveAnnotationProcessorPath` on `AbstractScalaCompile` and `JavaCompile` has been deprecated

Please use the `annotationProcessorPath` property on the task's `CompileOptions` directly.

### Deprecated announce plugins

The announce and build announcements plugins have been deprecated.

### Deprecated OSGi plugin

The osgi plugin has been deprecated. Builds should migrate to the biz.aQute.bnd plugin.

### Deprecated code quality plugins

- The FindBugs plugin has been deprecated because the project is unmaintained and does not work with bytecode compiled for Java 9 and above. Please consider using the SpotBugs plugin instead.
- The JDepend plugin has been deprecated because the project is unmaintained and does not work with bytecode compiled for Java 8 and above.

### Resolving configurations in other projects

It is now deprecated behavior to resolve a configuration in another project directly. Projects should interact via `project()` dependencies declared in configurations of the consuming project. Accessing and resolving configurations in other projects will now produce a deprecation warning.

### Resolving configurations from user-managed threads

It is also deprecated behavior to resolve a configuration from a thread that is not managed by Gradle (i.e. a thread created and managed by the user). Threads managed by Gradle (such as the workers that execute tasks) can still resolve configurations safely, but doing so from other threads will now produce a deprecation warning.

## External contributions

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

- Jonathan Leitschuh - Switch Jacoco plugin to use configuration avoidance APIs (gradle/gradle#6245)
- Jonathan Leitschuh - Switch build-dashboard plugin to use configuration avoidance APIs (gradle/gradle#6247)
- Jonathan Leitschuh - Fix nullability of the CreateStartScripts task properties (gradle/gradle#6704)
- Jonathan Leitschuh - Make Settings implement ExtensionAware (gradle/gradle#6685)
- Jonathan Leitschuh - Remove `@Incubating` from LifecycleBasePlugin (gradle/gradle#6901)
- Jonathan Leitschuh - Improve API documentation for `PathSensitivity` and `PathSensitive` (gradle/gradle#6983)
- Ben McCann - Remove Play 2.2 support (gradle/gradle#3353)
- Björn Kautler - No Deprecated Configurations in Build Init (gradle/gradle#6208)
- Georg Friedrich - Base Java Library Distribution Plugin on Java Library Plugin (gradle/gradle#5695)
- Stefan M. — Include Kotlin DSL samples in Gradle Wrapper, Java Gradle Plugin, OSGI Plugin and Organizing Gradle Projects user manual chapters (gradle/gradle#5923, gradle/gradle#6485, gradle/gradle#6539, gradle/gradle#6621)
- Stefan M. - Fix incoherent task name in the Authoring Tasks user manual chapter and other doc fixes (gradle/gradle#6581, gradle/gradle#7480)
- Jean-Baptiste Nizet — Include Kotlin DSL samples in Announcements, ANTLR, Base, EAR, Java Library Plugins, JaCoCo Plugins, Building Java Projects, Declaring Repositories, Dependency Locking, Dependency Types, Java Library, Java Testing, Artifact Management, IDEA Plugin, Application Plugin, Build Cache, Build Lifecycle, Declaring Dependencies, Inspecting Dependencies, Dependency Management for Java Projects, Working With Files, Working With Dependencies, Building Java Projects, Java Quickstart, Eclipse Plugin, Custom Tasks, Java Plugin, Signing Plugin, Composite Builds, TestKit, Multi Projects Builds, Managing Transitive Dependencies, Custom Plugins, Init Scripts, Scala Plugin, Managing Dependency Configurations, Groovy Plugin, Groovy Quickstart, Customizing Dependency Resolution Behavior, Publishing Overview and Publishing Ivy user manual chapters (gradle/gradle#6488, gradle/gradle#6500, gradle/gradle#6514, gradle/gradle#6518, gradle/gradle#6521, gradle/gradle#6540, gradle/gradle#6560, gradle/gradle#6559, gradle/gradle#6569, gradle/gradle#6556, gradle/gradle#6512, gradle/gradle#6501, gradle/gradle#6497, gradle/gradle#6571, gradle/gradle#6575, gradle/gradle#6586, gradle/gradle#6590, gradle/gradle#6591, gradle/gradle#6593, gradle/gradle#6597, gradle/gradle#6598, gradle/gradle#6602, gradle/gradle#6613, gradle/gradle#6618, gradle/gradle#6578, gradle/gradle#6660, gradle/gradle#6663, gradle/gradle#6678, gradle/gradle#6687, gradle/gradle#6588, gradle/gradle#6633, gradle/gradle#6637, gradle/gradle#6689, gradle/gradle#6509, gradle/gradle#6645, gradle/gradle#6596, gradle/gradle#6671, gradle/gradle#6668)
- Jean-Baptiste Nizet — Use proper subtype for useTestNG() (gradle/gradle#6520)
- Jean-Baptiste Nizet — Add documentation how to make a task cacheable using the runtime api (gradle/gradle#6691)
- Xiang Li and Theodore Ni - Make FileUtils#calculateRoots more efficient (gradle/gradle#6455)
- James Justinic Include Kotlin DSL samples in Ant, WAR Plugin, Checkstyle plugin, CodeNarc plugin, FindBugs plugin, JDepend plugin, PMD plugin user manual chapters (gradle/gradle#6492, gradle/gradle#6510, gradle/gradle#6522)
- James Justinic Support type-safe configuration for Checkstyle/FindBugs HTML report stylesheet (gradle/gradle#6551)
- Mike Kobit - Include Kotlin DSL samples in Lazy Configuration user manual chapter (gradle/gradle#6528)
- Kevin Macksamie - Switch distribution plugin to use configuration avoidance APIs (gradle/gradle#6443) and the application plugin (gradle/gradle#7003)
- Cliffred van Velzen - Allow logging null value (gradle/gradle#6665)
- Artem Zinnatullin - Update HttpCore from 4.4.9 to 4.4.10 and HttpClient from 4.5.5 to 4.5.6 (gradle/gradle#6709)
- Jakub Strzyżewski - Improve exception message for missing repository credentials when publishing (gradle/gradle#6379)
- Martin Dünkelmann - Raise default bytecode level to 1.8 in Maven2Gradle(gradle/gradle#4474)
- Alex Saveau - Report all files in directory as changed for incremental task for non-incremental change (gradle/gradle#6019)
- Thad House - Allow disabling of cache cleanup by the end user (gradle/gradle#6928)
- Dan Sanduleac - Conflict resolution can be bypassed, resulting in arbitrary version chosen (gradle/gradle#7049)
- Felipe Lima - Add support for excluding tests with TestFilter (gradle/gradle#6439)

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

## Upgrade Instructions

Switch your build to use Gradle 5.0 by updating your wrapper properties:

`./gradlew wrapper --gradle-version=5.0`

Standalone downloads are available at gradle.org/releases.

## Reporting Problems

If you find a problem with Gradle 5.0, 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 5.0, and we look forward to your feedback via Twitter or on GitHub.