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.
See 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, and Felipe Lima.
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.
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 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.
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.
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.
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.
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.
The init
task creates empty resource directories.
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.
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.
You can now specify a timeout duration for a task, after which it will be interrupted. Read more about task timeouts in the docs.
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.
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.
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 enthusiasts will be happy to read that this release supports running Gradle builds with JDK 11.
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.
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.
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.
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.
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.
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.
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.
The Gradle Native project continues to improve and evolve the native ecosystem support for Gradle.
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.
java-gradle-plugin
plugindistribution
pluginjacoco
pluginbuild-init
pluginIncrementalTaskInputs
and InputFileDetails
org.gradle.normalization
) including InputNormalizationHandler
FileNormalizer
and its subclasses@LocalState
, Task.getLocalState()
and TaskLocalState
Task.getDestroyables()
TaskState.getUpToDate()
and TaskState.getNoSource()
ValidateTaskProperties
taskAbstractArchiveTask.preserveFileTimestamps
and reproducibleFileOrder
propertiesForkOptions.javaHome
propertyProject.normalization
GroovyCompile.groovyCompilerJvmVersion
and javaToolChain
propertiesJavaVersion.VERSION_11
constant along with isJava11()
and isJava11Compatible()
methods--no-rebuild
option is no longer deprecatedA 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.
Known issues are problems that were discovered post release that are directly related to changes made in this release.
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
.
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.
The following properties are deprecated and will be removed in Gradle 6.0.
interactive
recompileScripts
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
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.
Gradle now emits a deprecation warning when you attempt to replace a task that may have already been used by something else.
Gradle now emits a deprecation warning when you attempt to replace a task with a type that's incompatible from the task being replaced.
Gradle now emits a deprecation warning when you attempt to replace a task that does not already exist.
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.
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.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()
or empty()
methods (or any other mutation method) to set an initial value, if required.
append
on JacocoTaskExtension
has been deprecatedSee above for details.
effectiveAnnotationProcessorPath
on AbstractScalaCompile
and JavaCompile
has been deprecatedPlease use the annotationProcessorPath
property on the task's CompileOptions
directly.
The announce and build announcements plugins have been deprecated.
The osgi plugin has been deprecated. Builds should migrate to the biz.aQute.bnd plugin.
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.
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.
Gradle can no longer be run on Java 7, but requires Java 8 as the minimum build JVM version. However, you can still use forked compilation and testing to build and test software for Java 6 and above.
The Tooling API can no longer connect to builds using a Gradle version below Gradle 2.6. The same applies to builds run through TestKit.
Gradle 5.0 requires a minimum Tooling API client version of 3.0. Older client libraries can no longer run builds with Gradle 5.0
The command line client now starts with 64m of heap instead of 1g. This may affect builds running directly inside the client VM using --no-daemon mode. We discourage the use of --no-daemon, but if you must use it, you can increase the available memory using the GRADLE_OPTS environment variable.
The Gradle daemon now starts with 512m of heap instead of 1g. Metaspace is now limited to 256m. It was unlimited before. Large projects may have to increase this setting using the org.gradle.jvmargs
property.
All workers, including compilers and test executors, now start with 512m of heap. The previous default was 1/4th of physical memory. Large projects may have to increase this setting on the relevant tasks, e.g. JavaCompile
or Test
.
Dependency resolutions fixes have been included in this release. By definition this could impact the set of resolved dependencies of your build. However the fixed issues are mostly about corner cases and combination with recent features and thus should have a limited impact.
When a dependency constraint matched a real dependency, it was made part of the graph. However if for some reason the dependency was later evicted from the graph, the constraint remained present. Now when the last non-constraint edge to a dependency disappears, all constraints for that dependency will be properly removed from the graph.
The configuration avoidance API introduced in Gradle 4.9 allows you to avoid creating and configuring tasks that are never used.
With the existing API, this example adds two tasks (foo
and bar
):
tasks.create("foo") { tasks.create("bar") }
When converting this to use the new API, something surprising happens: bar
doesn't exist. The new API only executes configuration actions when necessary, so the register()
for task bar
only executes when foo
is configured.
tasks.register("foo") { tasks.register("bar") // WRONG }
To avoid this, Gradle now detects this and prevents modification to the underlying container (through create
or register
) when using the new API.
The Java Library Distribution Plugin is now based on the Java Library Plugin instead of the Java Plugin. Additionally the created distribution will contain all artifacts of the runtimeClasspath
configuration instead of the deprecated runtime
configuration.
The previously deprecated support for Play Framework 2.2 has been removed.
See above for details.
Gradle will now, by convention, only look for Checkstyle configuration files in the root project's config/checkstyle directory. Checkstyle configuration files in subprojects — the old by-convention location — will be ignored unless you explicitly configure their path via checkstyle.configDir
or checkstyle.config
.
maven
plugin now publishes Maven 3 metadataThe maven
plugin used to publish the highly outdated Maven 2 metadata format. This has been changed and it will now publish Maven 3 metadata, just like the maven-publish
plugin.
The default tool versions of the following code quality plugins have been updated:
java-basic
to category/java/errorprone.xml
. We recommend configuring a ruleset explicitly, though.Several libraries that are used by Gradle have been upgraded:
Test
task have been upgraded from 1.0.3 to 1.3.1.In order to use S3 backed artifact repositories, it was previously required to add --add-modules java.xml.bind
to org.gradle.jvmargs
when running on Java 9 and above. Since Java 11 no longer contains the java.xml.bind
module, Gradle now bundles JAXB 2.3.1 (com.sun.xml.bind:jaxb-impl
) and uses it on Java 9 and above. Please remove the --add-modules java.xml.bind
option from org.gradle.jvmargs
, if set.
CopySpec.duplicatesStrategy
is no longer nullableFor better compatibility with the Kotlin DSL, the property setter no longer accepts null
as a way to reset the property back to its default value. Use DuplicatesStrategy.INHERIT
instead.
CheckstyleReports
and FindbugsReports
html
property now return CustomizableHtmlReport
For easier configurability from statically compiled languages such as Java or Kotlin.
The Javadoc
and Groovydoc
tasks now delete the destination dir for the documentation before executing. This has been added to remove stale output files from the last task execution.
DefaultTask
DefaultTask
are finalThe 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.
Previously:
``` class MyTask extends DefaultTask { // note: no annotation here final RegularFileProperty outputFile = newOutputFile() }
task myOtherTask { def outputFile = newOutputFile() doLast { ... } }
```
Now:
``` class MyTask extends DefaultTask { @OutputFile // property needs an annotation final RegularFileProperty outputFile = project.objects.fileProperty() }
task myOtherTask { def outputFile = project.objects.fileProperty() outputs.file(outputFile) // or to be registered using the runtime API doLast { ... } } ```
IdeaModule
no longer contain resourcesThe IdeaModule
Tooling API model element contains methods to retrieve resources and test resources so those elements were removed from the result of IdeaModule#getSourceDirs()
and IdeaModule#getTestSourceDirs()
.
source
field accessIn previous Gradle versions the source
filed in SourceTask
was accessible from subclasses. This is not the case anymore as the source
filed is now declared as private
.
The left shift (<<
) operator acted as an alias for adding a doLast
action to an existing task. It was deprecated since Gradle 3.2 and has now been removed.
Previously, it was deprecated for project and domain object names to be empty, start or end with .
or contain any of the following characters: /\:<>"?*|
. The use of such names now causes the build to fail.
publishing {}
block is now eagerIn Gradle 4.8, the old behavior of the publishing {}
block to defer its evaluation was deprecated. A new behavior that made its evaluation eager (like for any other block) was introduced and switched on using enableFeaturePreview('STABLE_PUBLISHING')
. Now, the old behavior has been removed and switching on the new one is no longer necessary. If you need to defer evaluation, please use afterEvaluate {}
.
Annotation processors on the compile classpath are no longer detected and used when compiling Java projects. This might cause compilation errors when upgrading to Gradle 5.0. Please add annotation processors to the annotation processor path instead.
With the removal of Maven 2 support, the methods to configure unique snapshot behavior have been removed. Maven 3 only supports unique snapshots, so these methods would have had no more effect. We decided to remove them instead of leaving a deprecated no-op in place.
getToSignArtifact
and setFile
from Signature
.targetSizeInMB
from DirectoryBuildCache
.dependsOnTaskDidWork
and deleteAllActions
from Task
.execute
, getExecuter
, setExecuter
, getValidators
and addValidator
from TaskInternal
.stopExecutionIfEmpty
and add
from FileCollection
.as
) FileCollection
to File[]
and File
.getBuildDependencies
from AbstractFileCollection
.file
and files
from TaskDestroyables
.styleSheet
from ScalaDocOptions
.newFileVar
and newDirectoryVar
from ProjectLayout
.property
from ProviderFactory
.property
from Project
.property
from Script
.leftShift
from Task
.RegularFileVar
.DirectoryVar
.PropertyState
.configureForSourceSet
from JavaBasePlugin
.classesDir
from JDepend
.testClassesDir
from Test
.classesDir
from SourceSetOutput
.performPostEvaluationActions
from IdeaPlugin
and EclipsePlugin
.setDestination(Object)
from ConfigurableReport
.@Option
and @OptionValues
annotations from the org.gradle.api.internal.tasks.options
package.@DeferredConfigurable
annotation.isDeferredConfigurable
from ExtensionSchema
null
as configuration action to the methods from
and to
on CopySpec
.bootClasspath
from CompileOptions
.file
, files
, and dir
on TaskInputs
is now impossible.file
, files
, and dir
on TaskOutputs
is now impossible.property
and properties
on TaskInputs
is now an error.JavaPluginConvention
is now abstract.ApplicationPluginConvention
is now abstract.WarPluginConvention
is now abstract.EarPluginConvention
is now abstract.BasePluginConvention
is now abstract.ProjectReportsPluginConvention
is now abstract.--no-search-upward
(-u
) option.--recompile-scripts
option.Classes in the internal org.gradle.util
package are no longer implicitly imported by default. Please either stop using internal classes (recommended) or import them explicitly at the top of your build file.
test.single
filter mechanism has been removed. You must select tests from the command-line with --tests
.test.debug
mechanism to enable debugging of JVM tests from the command-line has been removed. You must use --debug-jvm
to enable debugging of test execution.org.gradle.readLoggingConfigFile
system property no longer does anything — please update affected tests to work with your java.util.logging
settings.In earlier versions of Gradle, builds were allowed to replace tasks that may be automatically created. This was deprecated in Gradle 4.8 and has now been turned into an error.
Attempting to replace a built-in task will produce an error similar to the following:
Cannot add task 'wrapper' as a task with that name already exists.
The full list of built-in tasks that cannot be replaced:
wrapper
, init
, help
, tasks
, projects
, buildEnvironment
, components
, dependencies
, dependencyInsight
, dependentComponents
, model
, properties
SimpleFileCollection
.SimpleWorkResult
.getAddAction
from BroadcastingCollectionEventRegister
.settings.gradle
When invoking a build, Gradle TestKit now behaves like a regular Gradle invocation, and will search upwards for a settings.gradle
file that defines the build. Please ensure that all builds being executed with Gradle TestKit define settings.gradle
, even if this is an empty file.
--source-path
directly as a Java compiler argAdding -sourcepath
or --source-path
to the CompileOptions.compilerArgs
list is now prohibited. The source path for a JavaCompile
task should be set via the CompileOptions.sourcePath
property.
--processor-path
directly as a Java compiler argAdding -processorpath
or --processor-path
to the CompileOptions.compilerArgs
list is now prohibited. Annotation processors should instead be added to the annotationProcessor
configuration.
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.
Artifact configuration accessors are now typed NamedDomainObjectProvider<Configuration>
instead of simply Configuration
.
PluginAware.apply<T>(to)
was renamed PluginAware.applyTo<T>(target)
.
Both changes could cause script compilation errors.
See the Gradle Kotlin DSL release notes for more information and how to fix builds broken by the changes described above.
We would like to thank the following community members for making contributions to this release of Gradle.
@Incubating
from LifecycleBasePlugin (gradle/gradle#6901)PathSensitivity
and PathSensitive
(gradle/gradle#6983)We love getting contributions from the Gradle community. For information on contributing, please see gradle.org/contribute.
Switch your build to use Gradle 5.0-rc-1 by updating your wrapper properties:
./gradlew wrapper --gradle-version=5.0-rc-1
Standalone downloads are available at gradle.org/release-candidate.
If you find a problem with Gradle 5.0-rc-1, 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.