In a typical Gradle project, multiple configurations exist, such as compileClasspath and runtimeClasspath.

build.gradle.kts
dependencies {
    implementation("org.codehaus.groovy:groovy:3.0.1")
    runtimeOnly("io.vertx:vertx-lang-groovy:3.9.4")
}
build.gradle
dependencies {
    implementation 'org.codehaus.groovy:groovy:3.0.1'
    runtimeOnly 'io.vertx:vertx-lang-groovy:3.9.4'
}

These configurations are resolved independently, which can lead to situations where the same dependency appears in different versions across configurations.

For instance, a library used during compilation (compileClasspath) might resolve to version 1.0, while at runtime (runtimeClasspath), due to additional transitive dependencies, it might resolve to version 1.1. This discrepancy can cause unexpected behavior or runtime errors.

To address this, Gradle allows you to enforce consistent resolution of dependencies across configurations. By declaring that certain configurations should resolve dependencies consistently with others, you ensure that shared dependencies have the same version in both configurations.

Dependency resolution consistency is an incubating feature.

Implementing Consistent Resolution

For example, to ensure that the runtimeClasspath is consistent with the compileClasspath, you can configure your build.gradle(.kts) as follows:

build.gradle.kts
configurations {
    runtimeClasspath.get().shouldResolveConsistentlyWith(compileClasspath.get())
}
build.gradle
configurations {
    runtimeClasspath.shouldResolveConsistentlyWith(compileClasspath)
}

This setup directs Gradle to align the versions of dependencies in the runtimeClasspath with those resolved in the compileClasspath. If a version conflict arises that cannot be reconciled, Gradle will fail the build, prompting you to address the inconsistency.

Automatic Configuration in the Java Ecosystem

For Java projects, Gradle provides a convenient method to enforce this consistency across all source sets:

build.gradle.kts
java {
    consistentResolution {
        useCompileClasspathVersions()
    }
}
build.gradle
java {
    consistentResolution {
        useCompileClasspathVersions()
    }
}

This configuration ensures that all runtime classpaths are consistent with their corresponding compile classpaths, promoting reliable and predictable builds.

By implementing dependency resolution consistency, you can prevent subtle bugs and maintain uniformity in your project’s dependency versions across different classpaths.