Difference between implementation, API ,compile and runtimeOnly in Gradle Dependency

After updating to Android Studio 3.0 and creating a new project, I noticed that in build.gradle there is a new way to add new dependencies instead of compile there is implementation and instead of testCompile there is testImplementation.

Example:

implementation 'com.android.support:appcompat-v7:25.0.0'
testImplementation 'junit:junit:4.12'

instead of

compile 'com.android.support:appcompat-v7:25.0.0'
testCompile 'junit:junit:4.12'

Now let’s discuss one by one about each type-

  • implementation: When your module configures an implementation dependency, it’s letting Gradle know that the module does not want to leak the dependency to other modules at compile time. That is, the dependency is available to other modules only at runtime. Using this dependency configuration instead of api or compile can result in significant build time improvements because it reduces the amount of projects that the build system needs to recompile. For example, if an implementation dependency changes its API, Gradle recompiles only that dependency and the modules that directly depend on it. Most app and test modules should use this configuration.
  • api: When a module includes an api dependency, it’s letting Gradle know that the module wants to transitively export that dependency to other modules, so that it’s available to them at both runtime and compile time. This configuration behaves just like compile (which is now deprecated), and you should typically use this only in library modules. That’s because, if an api dependency changes its external API, Gradle recompiles all modules that have access to that dependency at compile time. So, having a large number of api dependencies can significantly increase build times. Unless you want to expose a dependency’s API to a separate test module, app modules should instead use implementation dependencies.
  • compileOnly: Gradle adds the dependency to the compilation classpath only (it is not added to the build output). This is useful when you’re creating an Android library module and you need the dependency during compilation, but it’s optional to have present at runtime. That is, if you use this configuration, then your library module must include a runtime condition to check whether the dependency is available, and then gracefully change its behavior so it can still function if it’s not provided. This helps reduce the size of the final APK by not adding transient dependencies that aren’t critical. This configuration behaves just like provided (which is now deprecated).
  • runtimeonly: Gradle adds the dependency to the build output only, for use during runtime. That is, it is not added to the compile classpath. This configuration behaves just like apk (which is now deprecated).

To know more about it check Google Android Developer link here.

Configuration Comparison Table:

Read the android doc for more detail:

https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_configurations_graph.

User the runtimeOnly build dependency Use Case

runtimeOnly libraries are the opposite, they are available at runtime but not at compile-time.

For example, you don’t need the concrete SLF4J logger(e.g. logback) at compile time (as you use the SLF4J classes in order to access it) but you need it at runtime as you want to use it.

Let’s look at the following example:

You have a library that uses the SLF4J:

compileOnly org.slf4j:slf4j-api:1.7.30

and you could have a project using the library:

implementation project(":yourlibrary")
implementation org.slf4j:slf4j-api:2.0.0-alpha1
runtimeOnly ch.qos.logback:logback:0.5

SLF4J detects the concrete logger at runtime, it does not need to know the logging library (like logback) at compile-time. This is why you can use runtimeOnly for the concrete logger.

Now try to understand Problem situation

Suppose you have a library called MyLibrary that internally uses another library called InternalLibrary. Something like this:

// 'InternalLibrary' module
public class InternalLibrary {
public static String giveMeAString(){
return "hello";
}
}
// 'MyLibrary' module
public class MyLibrary {
public String myString(){
return InternalLibrary.giveMeAString();
}
}

Suppose the MyLibrary build.gradle uses api configuration in dependencies{} like this:

dependencies {
api project(':InternalLibrary')
}

You want to use MyLibrary in your code so in your app's build.gradle you add this dependency:

dependencies {
implementation project(':MyLibrary')
}

Using the api configuration (or deprecated compile) you can access InternalLibrary in your application code:

// Access 'MyLibrary' (granted)
MyLibrary myLib = new MyLibrary();
System.out.println(myLib.myString());
// Can ALSO access the internal library too (but you shouldn't)
System.out.println(InternalLibrary.giveMeAString());

In this way the module MyLibrary is potentially "leaking" the internal implementation of something. You shouldn't (be able to) use that because it's not directly imported by you.

The implementation configuration was introduced to prevent this. So now if you use implementation instead of api in MyLibrary:

dependencies {
implementation project(':InternalLibrary')
}

you won’t be able to call InternalLibrary.giveMeAString() in your app code anymore.

This sort of boxing strategy allows Android Gradle plugin to know that if you edit something in InternalLibrary, it must only trigger the recompilation of MyLibrary and not the recompilation of your entire app, because you don't have access to InternalLibrary.

When you have a lot of nested dependencies this mechanism can speed up the build a lot. (Watch the video linked at the end for a full understanding of this)

CONCLUSIONS

  • When you switch to the new Android Gradle plugin 3.X.X, you should replace all your compile with the implementation keyword *(1). Then try to compile and test your app. If everything it's ok leave the code as is, if you have problems you probably have something wrong with your dependencies or you used something that now is private and not more accessible.
  • If you are a library maintainer you should use api for every dependency which is needed for the public API of your library, while use implementation for test dependencies or dependencies which must not be used by the final users.

For other use case example you can follow the below link:

https://tomgregory.com/how-to-use-gradle-api-vs-implementation-dependencies-with-the-java-library-plugin/

https://jeroenmols.com/blog/2017/06/14/androidstudio3/

--

--

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Abhishek Srivastava

Abhishek Srivastava

Senior Software Engineer | Android | Java | Kotlin|Xamarin Native Android|Flutter