Gradle Release Notes

Upgrade instructions

Switch your build to use Gradle 4.6 quickly by updating your wrapper properties:

gradle wrapper --gradle-version=4.6

Standalone downloads are available at gradle.org/releases.

New and noteworthy

Here are the new features introduced in this Gradle release.

JUnit 5 support

JUnit 5 is the latest version of the well-known JUnit test framework. JUnit 5 is composed of several modules:

JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage

The JUnit Platform serves as a foundation for launching testing frameworks on the JVM. JUnit Jupiter is the combination of the new programming model and extension model for writing tests and extensions in JUnit 5. JUnit Vintage provides a TestEngine for running JUnit 3 and JUnit 4 based tests on the platform.

Gradle now provides native support for JUnit Jupiter/Vintage Engine on top of JUnit Platform. To enable JUnit Platform support, you just need to add one line to your build.gradle:

test {
    useJUnitPlatform()
}

Moreover, Tagging and Filtering can be enabled via:

test {
    useJUnitPlatform {
        // includeTags 'fast'
        excludeTags 'slow'

        // includeEngines 'junit-jupiter', 'junit-vintage'
        // excludeEngines 'custom-engine'
    }
}

You can find more information on test grouping and filtering in the Java Plugin documentation.

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.1.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.1.0'
}

package foo.bar;

import org.junit.jupiter.api.Test;

public class JUnitJupiterTest {
    @Test
    public void ok() { 
    }
}

test {
    useJUnitPlatform()
}

dependencies {
    testCompileOnly 'junit:junit:4.12' 
    testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.1.0' 
}

Fail fast option for Test tasks

Gradle now supports stopping Test tasks after the first failed test. Projects with large test suites can take a long time to execute even though a failure occurred early on leading to unnecessary wait times (especially on CI). To enable this fail fast behavior in your build file, set the failFast property to true:

test {
    failFast = true
}

In addition, this behavior can be enabled from the command line for individual build invocations. An invocation looks like:

gradle integTest --fail-fast

More information is available in the Java Plugin documentation for test execution.

Allow declared reasons for dependency and resolution rules

In complex builds, it can become hard to interpret dependency resolution results and why a dependency declaration or a rule was added to a build script. To improve on this situation, we extended all the corresponding APIs with the capability to define a reason for each declaration or rule.

These reasons are shown in dependency insight reports and error messages if the corresponding declaration or rule influenced the resolution result. In the future, they will also be shown in build scans.

dependencies {
    implementation('org.ow2.asm:asm:6.0') {
        because 'we require a JDK 9 compatible bytecode generator'
    }
}

Dependency constraints for transitive dependencies

With dependency constraints, Gradle adds a mechanism to express constraints over transitive dependencies which are used during dependency resolution.

dependencies {
    implementation 'org.apache.httpcomponents:httpclient'
}

dependencies {
    constraints {
        implementation('org.apache.httpcomponents:httpclient:4.5.3') {
            because 'previous versions have a bug impacting this application'
        }
        implementation('commons-codec:commons-codec:1.11') {
            because 'version 1.9 pulled from httpclient has bugs affecting this application'
        }
    }
}

In the example, the version of commons-codec that is brought in transitively is 1.9. With the constraint, we express that we need at least 1.11 and Gradle will now pick that version during dependency resolution.

Compared to dependency management rules you can define in the resolution strategy, which are applied after dependency resolution to fix up the result, dependency constraints are declared information that participate in the dependency resolution process. This means that all constraints are considered in combination. For instance, if another dependency brings in an even higher version of commons-codec, Gradle will respect that.

Expressing the same in a traditional dependency substitution rule requires you to repeat part of the dependency resolution process manually – which is expensive and error prone. That is, you would have to inspect the version that was selected and implement a decision based on the version:

resolutionStrategy.eachDependency { DependencyResolveDetails details ->
    if (details.requested.group == 'commons-codec'
        && details.requested.name == 'commons-codec'
        && VersionNumber.parse(details.requested.version) < VersionNumber.parse('1.11')) {
            details.useVersion '1.11'
    }
}

Note: Dependency constraints are not yet published, but that will be added in a future release. This means that their use currently only targets builds that do not publish artifacts to maven or ivy repositories.

BOM import

Gradle now provides support for importing bill of materials (BOM) files, which are effectively .pom files that use <dependencyManagement> to control the dependency versions of direct and transitive dependencies. It works by declaring a dependency on a BOM.

dependencies {
    // import a BOM
    implementation 'org.springframework.boot:spring-boot-dependencies:1.5.8.RELEASE'

    // define dependencies without versions
    implementation 'com.google.code.gson:gson'
    implementation 'dom4j:dom4j'
}

Here, for example, the versions of gson and dom4j are provided by the Spring Boot BOM.

Note: This is a Gradle 5.0 feature preview, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding enableFeaturePreview('IMPROVED_POM_SUPPORT') in settings.gradle.

Support for optional dependencies in POM consumption

Gradle now creates a dependency constraint for each dependency declaration in a POM file with <optional>true</optional>. This constraint will produce the expected result for an optional dependency: if the dependency module is brought in by another, non-optional dependency declaration, then the constraint will apply when choosing the version for that dependency (e.g., if the optional dependency defines a higher version, that one is chosen).

Note: This is a Gradle 5.0 feature preview, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding enableFeaturePreview('IMPROVED_POM_SUPPORT') in settings.gradle.

Compile/runtime scope separation in POM consumption

Since Gradle 1.0, runtime scoped dependencies have been included in the Java compile classpath, which has some drawbacks:

• The compile classpath is much larger than it needs to be, slowing down compilation.
• The compile classpath includes runtime files that do not impact compilation, resulting in unnecessary re-compilation when these files change.

Now, if this new behavior is turned on, the Java and Java Library plugins both honor the separation of compile and runtime scopes. Meaning that the compile classpath only includes compile scoped dependencies, while the runtime classpath adds the runtime scoped dependencies as well. This is in particular useful if you develop and publish Java libraries with Gradle where the api/implementation dependencies separation is reflected in the published scopes.

Note: This is a Gradle 5.0 feature preview, which means it is a potentially breaking change that will be activated by default in Gradle 5.0. It can be turned on in Gradle 4.6+ by adding enableFeaturePreview('IMPROVED_POM_SUPPORT') in settings.gradle.

Customizable metadata file resolution

Gradle now allows you to explicitly state for which metadata files it should search in a repository. Use the following to configure Gradle to fail-fast resolving a dependency if a POM file is not found first.

repositories {
     mavenCentral {
         metadataSources {
             mavenPom() // Look for Maven '.pom' files
             // artifact() - Do not look for artifacts without metadata file
         }
     }
}

This avoids a 2nd request for the JAR file when the POM is missing, making dependency resolution from Maven repositories faster in this case.

Convenient declaration of annotation processor dependencies

It is now even easier to add annotation processors to your Java projects. Simply add them to the annotationProcessor configuration:

dependencies {
    annotationProcessor 'com.google.dagger:dagger-compiler:2.8'
    implementation 'com.google.dagger:dagger:2.8'
}

Declaring annotation processors on a separate configuration improves performance by preserving incremental compilation for tasks that don't require annotation processors.

Tasks API allows custom command-line options

Sometimes a user wants to declare the value of an exposed task property on the command line instead of the build script. Being able to pass in property values on the command line is particularly helpful if they change more frequently. With this version of Gradle, the task API now supports a mechanism for marking a property to automatically generate a corresponding command line parameter with a specific name at runtime. All you need to do is to annotate a setter method of a property with Option.

The following examples exposes a command line parameter --url for the custom task type UrlVerify. Let's assume you wanted to pass a URL to a task of this type named verifyUrl. The invocation looks as such: gradle verifyUrl --url=https://gradle.org/. You can find more information about this feature in the documentation on declaring command-line options.

import org.gradle.api.tasks.options.Option;

public class UrlVerify extends DefaultTask {
    private String url;

    @Option(option = "url", description = "Configures the URL to be verified.")
    public void setUrl(String url) {
        this.url = url;
    }

    @Input
    public String getUrl() {
        return url;
    }

    @TaskAction
    public void verify() {
        getLogger().quiet("Verifying URL '{}'", url);

        // verify URL by making a HTTP call
    }
}

Rich command-line arguments for Test, JavaExec or Exec tasks

Gradle 4.5 added the possibility to add CommandLineArgumentProviders to CompileOptions, thus enabling plugin authors to better model tools like annotation processors.

Now we introduce CommandLineArgumentProviders to Exec, JavaExec and Test, both to model command line arguments (Exec and JavaExec) as well as JVM options (JavaExec and Test).

For example, the built-in jacoco plugin uses this new feature to declare the inputs and outputs of the JaCoCo agent added to the test task.

class JacocoAgent implements CommandLineArgumentProvider {

    private final JacocoTaskExtension jacoco;

    public JacocoAgent(JacocoTaskExtension jacoco) {
        this.jacoco = jacoco;
    }

    @Nested
    @Optional
    public JacocoTaskExtension getJacoco() {
        return jacoco.isEnabled() ? jacoco : null;
    }

    @Override
    public Iterable<String> asArguments() {
        return jacoco.isEnabled() ? ImmutableList.of(jacoco.getAsJvmArg()) : Collections.<String>emptyList();
    }

}

task.getJvmArgumentProviders().add(new JacocoAgent(extension));

For this to work,