Written by Vincent Brison
on March 17, 2016

Gradle dependencies

Recently we presented Gradle. Today we will talk about managing dependencies through Gradle, which is a great feature, especially for Android.

Using Gradle you can easily manage dependencies like Play Services, support libraries, or any other library, in a Maven way. Thus, we can ask ourself some questions about this management:

How are dependencies managed when two dependencies of a same project share a dependency but with conflicting versions?
What is transitive dependency resolution?
What is the purpose of optional dependency?

This article try to solve those questions in a clear way, using well known examples of the Android world.

Showcase project

The following project on GitHub illustrates the examples discussed in this article. You may clone this repository to be able to try the examples by yourself. For each example a specific commit is available.

How to add a dependency

Example: (commit)

Calligraphy

compile 'uk.co.chrisjenx:calligraphy:2.1.0'

This is a very classic example of using compile, and adding dependency to your project using Gradle. But what if this dependency has itself other dependencies? To be able to list all the dependencies (and sub dependencies) from your project you can use the following command:

./gradlew dependencies app:dependencies

This command will list the dependencies for each “configuration”: https://docs.gradle.org/current/dsl/org.gradle.api.artifacts.Configuration.html of the module app. It may be interesting to filter the configurations to reduce the output to the compile configuration (which is the most interesting in our case).

./gradlew dependencies app:dependencies --configuration compile

We obtain the following result:

compile - Classpath for compiling the main sources.
--- uk.co.chrisjenx:calligraphy:2.1.0
\--- com.android.support:appcompat-v7:22.1.1
\--- com.android.support:support-v4:22.1.1
\--- com.android.support:support-annotations:22.1.1

We can see that calligraphy depends on appcompat-v7, which itself depends on support-v4, which in turn depends on support-annotations. By default those dependencies will be resolved without adding them to the module app. Those dependencies are resolved transitively.

Transitive dependencies

Example: (commit)

Let’s say our app module is already using support library appcompat-v7, but in a higher version, 23.1.1. Which version of appcompat-v7 should be finally used by the app module, knowing calligraphy already depends on version 22.1.1 of appcompat-v7? Let’s analyse the dependencies with Gradle command:

compile - Classpath for compiling the main sources.
+--- uk.co.chrisjenx:calligraphy:2.1.0
|    --- com.android.support:appcompat-v7:22.1.1 -> 23.1.1
|         --- com.android.support:support-v4:23.1.1
|              --- com.android.support:support-annotations:23.1.1
--- com.android.support:appcompat-v7:23.1.1 (*)

The appcompat-v7:22.1.1 dependency of calligraphy is changed into ppcompat-v7:23.1.1. By default, dependency resolution is transitive, which let all the dependencies (the dependencies of the dependencies) to be resolved in recursive way, taking higher version if there is a conflict. This is how support-v4 and support-annotations are automatically imported as dependencies of the module app (there is no need to add them to the build.gradle).

Dependencies resolution strategy

Exemple: (commit)

We can add the following block to our build.gradle to be notified when our project has the same dependency in two different versions:

configurations.all {
  resolutionStrategy {
    failOnVersionConflict()
  }
}

This block will trigger an error during the build, forcing us to manage manually the version conflict. By default, Gradle uses its own resolution strategy of dependencies, where when a version conflict occurs, it takes the highest version. You can define your own resolution strategy, like the one above (documentation).

Filter dependencies

Exemple: (commit)

Moreover, we can directly configure how Gradle must set up dependencies. For example, if we take the library simple-xml, the dependency analysis result is:

compile - Classpath for compiling the main sources.
--- org.simpleframework:simple-xml:2.7.1
+--- stax:stax-api:1.0.1
+--- stax:stax:1.2.0
|    \--- stax:stax-api:1.0.1
\--- xpp3:xpp3:1.1.3.3

This configuration is not compatible with Android for the following reasons:

xpp3 is directly included in Android framework. The classes are already included in it. We can not include another version of xpp3 with the same package name and the same class names.
stax is using a pacakge name protected by the Android framework (java.xml.*).Nevertheless simple-xml can work on Android without any concern since its stax dependency is optional (stax availability is checked at runtime).

But we need to modify our build.gradle to not include stax during the compilation (btw. the build system is clever enough to ignore xpp3, only a warning will be shown). We can use the following syntax to exclude stax (commit):

compile('org.simpleframework:simple-xml:2.7.1'){
  exclude module: 'stax'
  exclude module: 'stax-api'
  exclude module: 'xpp3' // optional
}

The corresponding DSL documentation is available here.

For library developers

With the previous example, we saw that simple-xml can work without stax. If we take a look at its pom.xml, we can see that stax is a non optional dependency. But it is possible to define a dependency as an optional dependency. Lets consider a library L(ibrary) with a library O(ptional) as optional, the L transitive dependency resolution will not include the O dependency.

In the case of simple-xml, if stax and xpp3 were optional dependencies, we could define the simple-xml dependency as:

compile 'org.simpleframework:simple-xml:2.7.1'

This is actually the case for Retrofit 1 where OkHttp is an optional dependency. Thus, at runtime, if OkHttp is available, Retrofit will use OkHttp as default HTTP client, otherwise it will use the default HTTP client provided by the plateform on which Retrofit is used. We can also note that Retrofit 1 is not using Gradle, but Maven. We can explain this choice for the reason that declaring a dependency as optional is not yet supported natively by Gradle, but some solutions are presently available to be able to use it:

As this thread explains, it is possible to use optional dependency by hand.
There is also a plugin (gradle-extra-configurations-plugin) which brings the optional dependency support to Gradle build system.

Conclusion

Managing dependencies through Gradle is very useful. Having a clear understanding of how to configure these dependencies let you manage in a meaningful way the evolution of your dependencies in the lifecycle of an Android project. More than that, a very precise use of dependency configuration by libraries developers can be useful, to be easily included in other projects, as Retrofit does.

Special thanks to Adrien Couque who greatly helped me to write this article.

← Previous article Top