Gradle Compile-only Dependencies

One of the most highly anticipated Gradle features has arrived in Gradle 2.12, support for declaring compile only dependencies (release notes here). For Java developers coming from Maven, compile only dependencies function similarly to Maven’s “provided” scope, allowing you to declare non-transitive dependencies used only at compilation time. While a similar capability has been available for users of the Gradle War Plugin, compile only dependencies can now be declared for all Java projects using the Java Plugin.

These can be leveraged for a number of use cases, including, but not limited to:

• Dependencies required only during source compilation, such as source only annotations or annotation processors
• Optional dependencies which are required at compilation time, but only needed at runtime only when using certain application features
• Dependencies whose API is needed at compile time, but an implementation is expected to be provided by the project’s consumer or runtime environment

Compile only dependencies are distinctly different than regular “compile” dependencies. They are not included on the runtime classpath and are non-transitive, meaning they are not included in dependent projects. This is true when using Gradle project dependencies and also when publishing to Maven or Ivy repositories. In the latter case, compile only dependencies are simply omitted from published metadata.

As part of our goal of quality IDE support, compile only dependencies continue to work with Gradle’s IDEA and Eclipse plugins. When used in conjunction with IntelliJ IDEA, compile only dependencies are mapped to IntelliJ’s “provided” scope. With Eclipse, compile only dependencies are not exported via project dependencies.

In the Gradle model we consider tests to be a “consumer” of the production code. With this in mind, compile only dependencies are not inherited by the test classpath. The intention is that tests, like any other runtime environment, should provide their own implementation, either in the form of mocks or some other dependency.

Declaring compile only dependencies is simple, just assign dependencies to the new “compileOnly” configuration for the appropriate source set.

dependencies{

compileOnly 'javax.servlet:servlet-api:2.5'

As a result of the addition of the “compileOnly” configuration, the “compile” configuration no longer represents a complete picture of all compile time dependencies. When needing reference a compile classpath in build scripts or custom plugins, the appropriate source set’s compileClasspath property should be used instead.

For more information be sure to check out the Java Plugin chapter of the Gradle user guide and as always, we welcome any feedback and questions. Feel free to tell us what you think about this, or any other topic, at discuss.gradle.org.