Gradle Release Notes

Version 3.0

The Gradle team is pleased to announce Gradle 3.0.

Performance continues to be a focus for the Gradle team and the third major release reflects this. The Gradle Daemon is a key performance enhancer, making builds up to 75% faster, but it needed to be explicitly enabled in previous versions of Gradle. This is no longer necessary as the Daemon is now enabled by default in 3.0. We've put a lot of effort into fixing the most significant issues with the Gradle Daemon, especially on Windows platforms. We have also been working hard to make the Gradle Daemon aware of its health and impact to the system it's running on and use this information for self-healing actions as well as better daemon status reporting. The Gradle Daemon is the foundation for a great Gradle experience.

Ever wished for better IDE support when writing Gradle build scripts? This release provides the first support for Gradle Script Kotlin, which is a Kotlin-based build language for Gradle scripts. Its deep integration with both IDEA and Eclipse provides many of the things you would expect from an IDE such as auto-completion, refactoring, navigation to source, and more. Groovy is still the primary build language for Gradle scripts and will always be supported, but we are working intensely to make Gradle Script Kotlin fully production ready by the end of the year in order to provide the best possible development experience to Gradle users. See Chris Beams's blog post for more information about this exciting new feature.

Additionally, Gradle 3.0 provides support for running on the latest Java 9 EAP builds. Users can also build and run tests using these early versions of JDK 9, but there are some limitations. Check out the section on Java 9 support below for more details.

With the release of Gradle 3.0, it's a good time to reflect on the progress we've made over the last 2 years. Check out some of the improvements since Gradle 2.0. Lots of reasons to upgrade!

We're also pleased to make available a draft of our new Performance Guide. This is intended to be a short guide that shows you how to dramatically improve your build performance in the time it takes to eat lunch. Check it out and please provide any feedback via the guide's GitHub Issues.

Table Of Contents

New and noteworthy

Here are the new features introduced in this Gradle release.

Improved Gradle Daemon, now enabled by default

As mentioned above, the Gradle Daemon is now more robust, efficient and self-aware. It has now been enabled by default to make your builds faster than ever. If for some reason you encounter problems, it can always be disabled if necessary.

View the status of Gradle Daemons

Before Gradle 3.0, there was no easy way to determine the status of a running Gradle Daemon or why a Daemon might have stopped. With this release, you can now check the status of running and recently stopped daemons using the --status command and get better insight into the state your Gradle environment.

$> gradle --status
   PID STATUS   INFO
 43536 BUSY     3.0
 43542 IDLE     3.0
 43418 STOPPED  (stop command received)
 43366 STOPPED  (stop command received)

Note that the status command currently does not list Gradle Daemons with version < 3.0. More details are available in the User Guide.

View Daemon information in Gradle Cloud Services

Information about the Gradle Daemon is now being captured in your Build Scans and can be viewed in Gradle Cloud Services. You can see information such as the number of builds that have been run in the Daemon, the number of Daemons that were running on the system when the build occurred, as well as reasons for why a Daemon may have been stopped. Along with all of the other great information in a Build Scan, this captures the state of the Daemon at the time a build executes and gives you insight into factors that might have affected that build's performance. If you haven't created a Build Scan yet, give it a try!

Better IDE support for writing build scripts

The Gradle team and JetBrains have been collaborating to provide the best possible IDE support for writing Gradle build scripts. Gradle 3.0 supports version 0.3.0 of
Gradle Script Kotlin, a statically typed build language based on Kotlin.

So what does a Gradle Script Kotlin build look like? Here's an example:

import org.gradle.api.tasks.*

apply<ApplicationPlugin>()

configure<ApplicationPluginConvention> {
    mainClassName = "org.gradle.samples.HelloWorld"
}

repositories {
    jcenter()
}

dependencies {
    compile("commons-lang:commons-lang:2.4")
    testCompile("junit:junit:4.12")
}

task<Copy>("copyConfig") {
    from("src/main/conf")
    into("build/conf")
    exclude("**/*.old")
    includeEmptyDirs = false
}

This looks very similar to a Groovy build script, but when you load it in either IDEA or Eclipse, suddenly development is a much better experience. You now have code auto-completion, refactoring, and other features you would expect from an IDE in your build.gradle.kts. You can still use all of your plugins written in Java or Groovy but also take advantage of the power of first-class development support. Take a look and give it a try!

We'll continue to enhance this support in future versions of Gradle, so if you discover any issues, please let us know via the project's GitHub Issues.

Parallel task execution improvements

Gradle 3.0 makes it easier to manage the resources that Gradle uses. The Test task type now honors the max-workers setting for the test processes that are started. This means that Gradle will now run at most max-workers tasks and test processes at the same time.

If you need to return to the old behavior, you can limit the number of forked processes:

tasks.withType(Test) {
     maxParallelForks = 1
}

Initial Java 9 support

Gradle 3.0 contains initial support for running Gradle on Java 9 as well as compiling, testing and running Java 9 applications from Gradle.

Preliminary support for the JDK 9 -release compiler flag has been added as well. It can be specified via compilerArgs, e.g.

compileJava.options.compilerArgs.addAll(['-release', '7'])

The following plugins have known issues with Java 9:

When using continuous build on Java 9, the following constraints apply due to class access restrictions related to Jigsaw:

Additionally, when publishing to S3 backed Maven and Ivy repositories, -addmods java.xml.bind will have to be added to the JVM parameters when using Java 9.

GRADLE_OPTS="-addmods java.xml.bind '-Dorg.gradle.jvmargs=-addmods java.xml.bind'"

Please report any issues you may experience running or building with Java 9 on the Gradle Forums.

Improved plugins DSL

There are times when it might be useful to resolve a plugin without actually applying it to the current project, for example:

Previously, this could only be done with the buildscript DSL syntax, but this is now possible via the plugins DSL, too:

plugins {
    id 'my.special.plugin' version '1.0' apply false
}

subprojects {
    if (someCondition) {
        apply plugin 'my.special.plugin'
    }
}

Note the apply false at the end of the plugin declaration. This instructs Gradle to resolve the plugin and make it available on the classpath, but not to apply it.

Incremental build improvements

Tracking changes in the task's code

A task is up-to-date as long as its inputs and outputs remain unchanged. Previous versions of Gradle did not consider the code of the task as part of the inputs. This could lead to incorrect behavior where the implementation of a task could change but the task might still be marked as UP-TO-DATE even though it would actually create different outputs. Gradle now recognizes when a task, its actions, or its dependencies change between executions and properly marks the task as out-of-date.

New task property annotations

Since 3.0, every task property should specify its role via one of the task property annotations:

  • an input or output of the task (@Input, @Nested, @InputDirectory, @OutputFile etc.)
  • an injected service (@Inject)
  • a property that influences only the console output of the task (the new @Console annotation)
  • an internal property that should not be considered for up-to-date checks (the new @Internal annotation)

When using the java-gradle-plugin, a warning is printed during validation for any task property that is not annotated.

Tracking properties for input and output files

From now on Gradle tracks which property each input and output file belongs to. With this improvement it can now recognize when files are moved between properties. Registering the property name works automatically for task input and output properties annotated with @InputFiles, @OutputFile etc.

Input and output files registered via TaskInputs.files(), TaskOutputs.dir() and similar methods have a new mechanism to register the property name:

task example {
    inputs.file "input.txt" withPropertyName "inputFile"
}

Faster Dependency Resolution

In Gradle 3.0, resolving already-downloaded external dependencies is 5-10% faster than previous versions. Much of the time savings can be attributed to switching from caching the metadata about dependencies as XML to a binary format which is much quicker to serialize and deserialize.

Improvements to the eclipse-wtp plugin

Before Gradle 3.0, the eclipse-wtp plugin defined external dependencies for a Java project in the WTP component descriptor. This lead to the issues detailed in GRADLE-2123. This has been fixed so that dependencies are now generated in the proper metadata locations according to the type of project being configured.

Additionally, the eclipse-wtp plugin now fully leverages Gradle's dependency resolution engine. As a result, dependency customisations such as substitution rules and forced versions work with WTP projects.

Lastly, if a project applies the war or ear plugins, applying the eclipse plugin now also applies eclipse-wtp. This makes configuration simpler, especially when using Eclipse Buildship.

New features in the EclipseProject model.

The EclipseProject model has been enhanced with many new features:

This allows Tooling API clients (such as Eclipse Buildship) to provide more robust and complete IDE integration.

Plugin library upgrades

Several libraries that are used by Gradle plugins have been upgraded:

Improvements since Gradle 2.0

A lot has changed since Gradle 2.0 was released in July of 2014. First of all, performance has been improved dramatically in all phases of the build, including configuration time, build script compilation, incremental builds and native compilation, as well as test execution and report generation to name a few. We've improved the Daemon significantly, adding performance monitoring and resource awareness, fixing known issues, and ultimately enabling it by default so that all builds experience the performance gains it brings to the table. Gradle 3.0 represents a significantly faster and more efficient Gradle than it was two years ago.

We've also made good strides in improving the experience of plugin development. The Gradle TestKit is an out-of-the-box toolkit for functionally testing your Gradle plugins. The Plugin Development Plugin helps you set up your plugin project by adding common dependencies to the classpath and providing validation of the plugin metadata when building the archive. Finally, the Plugin Publishing Plugin helps you to publish your plugins to the Gradle Plugin Portal and share them with the rest of the community.

Dependency Management has gotten some love, too. We've added component selection rules, module replacement rules, and dependency substitution rules. We've provided support for S3 repositories as well as configurable HTTP authentication, including preemptive authentication. We've even added support for compile-only dependencies. Publishing dependencies is also more powerful and you can now publish to S3 and SFTP repositories, implement Maven or Ivy dependency exclusions, as well as publish Ivy extra attributes in the artifact metadata. You can even publish your plugins to a private repository and then resolve them using the plugins DSL.

On the developer experience side of the house, you can now run continuous builds, where Gradle actively detects changes to the inputs of your tasks and proactively re-executes the build when changes occur. Our Tooling API is now considerably better with support for build cancellation, build progress events, and the ability to run specific test classes or methods. These improvements have all contributed to the release of Eclipse Buildship which provides first-class support for building, testing and running Gradle projects in Eclipse.

There's been substantial work on the plugins delivered with the Gradle distribution, too. We've added the ability to build, test and run applications using the Play Framework. Support for Native builds continues to improve with support for parallel compilation, cross compilation and pre-compiled headers. We've also introduced a DSL for declaring test suites and added support for testing native components with Google Test. We've also continued to evolve the Software Model and rule based model configuration that these plugins are built on. It is now possible to configure the model through DSL and view component and model reports as well as create new types of rules such as validation and defaults rules.

Gradle 3.0 represents a significant improvement over Gradle 2.0 in terms of functionality, performance and experience. Looking forward, we'll continue to work on making Gradle the best build system on the planet, but for now, we hope you enjoy using 3.0 as much as we've enjoyed working on it!

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.

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

Chaining TaskInputs and TaskOutputs methods

Chaining the following method calls is now deprecated:

With Gradle 3.0, the following now produces a deprecation warning:

task myTask {
    inputs.file("input1.txt").file("input2.txt")
}

The chaining of the file(Object) method has been deprecated and is scheduled to be removed in Gradle 4.0. Please use the file(Object) method on TaskInputs directly instead.

Jetty Plugin

The Jetty plugin has been deprecated and will be removed in Gradle 4.0. Consider using the more feature-rich Gretty plugin instead.

Potentially breaking changes

Running Gradle on Java 6 is no longer supported

Gradle itself now requires Java 7 or better to run, but compiling project sources and running tests with Java 6 is still supported. See Compiling and testing for Java 6 in the Gradle Userguide. There are also instructions on how to compile and test Groovy and Scala for Java 6.

Compiling and testing with Java 5 is no longer supported

Support for compiling and testing on Java 5 has been removed.

Sonar plugin has been removed

The legacy Sonar plugin has been removed from the Gradle distribution. It is superseded by the official plugin from SonarQube.

The eclipse-cdt plugin has been removed

The eclipse-cdt plugin is no longer supported and has been removed.

Unique default test result and report directories for Test tasks

The default location of reports produced by tasks of type Test have changed to incorporate the task name when used with the Java Plugin. This allows multiple tasks of type Test to produce non-conflicting default report and result directories without additional configuration.

When the Java, Groovy or Scala plugin is applied, the report directory for a task of type Test with the name integrationTest is now $buildDir/reports/tests/integrationTest and the test results directory is $buildDir/test-results/integrationTest.

This means the built-in test task reports are in a different location. To revert to the previous behaviour, the reports output directory of Test tasks can be configured explicitly:

test.reports.html.destination = testReportDir // build/reports/tests
test.reports.xml.destination = testResultDir // build/test-results

Ant-Based Scala Compiler has been removed

The deprecated Ant-Based Scala Compiler has been removed from Gradle 3.0 and the Zinc Scala Compiler is now used exclusively. The following properties related to the Ant-Based compiler have been removed from the ScalaCompile task:

Support for TestNG JavaDoc annotations has been removed

The support for declaring TestNG tests via JavaDoc annotations has been removed. As such, the Test.testSrcDirs and the methods on TestNGOptions have also been removed.

Task property annotations (e.g., @Input) on interfaces

In previous versions, annotations on task properties such as @InputFile and @OutputDirectory were only taken into account when they were declared on the task class itself (or one of its super-classes). With Gradle 3.0, annotations declared on implemented interfaces are also taken into account.

eclipse-wtp handling of external dependencies changed

For Java projects, the eclipse-wtp plugin adds external dependencies to the classpath instead of the WTP component file. Any customizations related to external dependencies that were made in the eclipse.wtp.component.file hooks now need to be moved to the eclipse.classpath.file hooks instead.

eclipse-wtp is automatically applied to war or ear projects with eclipse

Projects that have the war or ear plugins applied in conjunction with the eclipse plugin will now have the eclipse-wtp plugin applied automatically. If desired, this support can be removed using the following configuration:

eclipse.project {
    natures.removeAll { it.startsWith('org.eclipse.wst') }
    buildCommands.removeAll {         
        it.name.startsWith('org.eclipse.wst')
    }
}

Eclipse model contains classpath attributes for project and external dependencies

The EclipseProjectDependency and EclipseExternalDependency models now contain ClasspathAttribute objects. By default, the JavaDoc location attribute and WTP deployment attributes are also populated.

Any customizations made via eclipse.classpath.file.beforeMerged and eclipse.classpath.file.whenMerged are also reflected.

NamedDomainObjectContainers no longer create objects when using explicit parameter syntax

In previous versions of Gradle, the following would create a new SourceSet named foo:

sourceSets {
    it.foo {}
}

This behavior was unintended and has been removed. The above code will now cause an exception if foo has not already been defined.

Creation must now use the implicit syntax:

sourceSets {
    foo {}
}

Changes to previously deprecated APIs

Groovy to Java conversions

For performance reasons, all classes in Gradle's public API have been converted from Groovy to Java.

As a consequence, these classes no longer extend GroovyObject. In order to retain binary compatibility, public API classes that have been converted are decorated with GroovyObject at runtime. This means plugins written for Gradle 2.x should continue working with Gradle 3.x.

We are planning to drop the runtime GroovyObject decoration with Gradle 4.0. This means that plugins compiled against Gradle 2.x will no longer work with Gradle 4.0. Plugins that are compiled with Gradle 3.0 will not have references to GroovyObject and will remain compatible with Gradle 4.0. Plugins compiled with Gradle 3.0 will also work with Gradle 2.x as long as they confine themselves to the Gradle 2.x API.

When recompiling your plugin with Gradle 3.0, you may need to make some changes to make it compile.

One instance of this is when you use += in a statically compiled Groovy class. See GROOVY-7888.

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.