Understanding the difference between libraries and applications
A key concept in dependency management with Gradle is the difference between consumers and producers.
When you build a library, you are effectively on the producer side: you are producing artifacts which are going to be consumed by someone else, the consumer.
A lot of problems with traditional build systems is that they don’t make the difference between a producer and a consumer.
A consumer needs to be understood in the large sense:
a project that depends on another project is a consumer
a task that depends on an artifact is a finer grained consumer
In dependency management, a lot of the decisions we make depend on the type of project we are building, that is to say, what kind of consumer we are.
A producer may want to generate different artifacts for different kinds of consumers: for the same source code, different binaries are produced. Or, a project may produce artifacts which are for consumption by other projects (same repository) but not for external use.
A typical example in the Java world is the Guava library which is published in different versions: one for Java projects, and one for Android projects.
However, it’s the consumer responsibility to tell what version to use, and it’s the dependency management engine responsibility to ensure consistency of the graph (for example making sure that you don’t end up with both Java and Android versions of Guava on your classpath). This is where the variant model of Gradle comes into play.
In Gradle, producer variants are exposed via consumable configurations.
In order for a producer to compile a library, it needs all its implementation dependencies on the compile classpath. There are dependencies which are only required as an implementation detail of the library and there are libraries which are effectively part of the API.
However, a library depending on this produced library only needs to "see" the public API of your library and therefore the dependencies of this API. It’s a subset of the compile classpath of the producer: this is strong encapsulation of dependencies.
The consequence is that a dependency which is assigned to the
implementation configuration of a library does not end up on the compile classpath of the consumer.
On the other hand, a dependency which is assigned to the
api configuration of a library would end up on the compile classpath of the consumer.
At runtime, however, all dependencies are required.
Gradle makes the difference between different kinds of consumer even within a single project: the Java compile task, for example, is a different consumer than the Java exec task.
More details on the segregation of API and runtime dependencies in the Java world can be found here.
Whenever, as a developer, you decide to include a dependency, you must understand that there are consequences for your consumers. For example, if you add a dependency to your project, it becomes a transitive dependency of your consumers, and therefore may participate in conflict resolution if the consumer needs a different version.
A lot of the problems Gradle handles are about fixing the mismatch between the expectations of a consumer and a producer.
However, some projects are easier than others:
if you are at the end of the consumption chain, that is to say you build an application, then there are effectively no consumer of your project (apart from final customers): adding exclusions will have no other consequence than fixing your problem.
however if you are a library, adding exclusions may prevent consumers from working properly, because they would exercise a path of the code that you don’t
Always keep in mind that the solution you choose to fix a problem can "leak" to your consumers. This documentation aims at guiding you to find the right solution to the right problem, and more importantly, make decisions which help the resolution engine to take the right decisions in case of conflicts.