Gradle Implementation vs API configuration

From: https://stackoverflow.com/questions/44413952/gradle-implementation-vs-api-configuration

I think this topic needs a bit more coverage because maybe is not so immediate for every developer.

Gradle compile keyword has been deprecated in favor of the new api and implementationkeywords.

I will not explain api, because it's the same thing as using the old compile, so if you replace all your compile with api everything will works as always.

To understand the implementation keyword we need an example.

EXAMPLE

We have this library called MyLibrary where internally we are using another library called InternalLibrary. Something like this:

//internal library module
public class InternalLibrary {
    public static String giveMeAString(){
        return "hello";
    }
}

//my library module
public class MyLibrary {
    public String myString(){
        return InternalLibrary.giveMeAString();
    }
}

The build.gradle dependencies of MyLibrary its like this:

dependencies {
    api project(':InternalLibrary')
}

Now in your code you want to use MyLibrary so you should have a build.gradle with this dependency

dependencies {
    api project(':MyLibrary')
}

In your application code, with the api keyword (or using the old compile) you can access both MyLibrary and InternalLibrary.

//so you can access the library (as it should)
MyLibrary myLib = new MyLibrary();
System.out.println(myLib.myString());

//but you can access the internal library too (and you shouldn't)
System.out.println(InternalLibrary.giveMeAString());

In this way you are potentially "leaking" the internal implementation of something that you shouldn't use because it's not directly imported by you.

To prevent this, Gradle has created the new implementation keyword, so now if you switch apito implementation in your MyLibrary

dependencies {
    implementation project(':InternalLibrary')
}

And in your app build.gradle

dependencies {
    implementation project(':MyLibrary')
}

you won't be able to call InternalLibrary.giveMeAString() in your app code anymore. While if MyLibrary uses the api keyword to import InternalLibrary, in your app you will be able to call InternalLibrary.giveMeAString() without problems, independently if you use api or implementation to add MyLibrary to your app.

Using this sort of boxing strategy the Android Gradle plugin knows that if you edit something in InternalLibrary it will trigger the recompilation of MyLibrary only. It will not trigger the recompilation of your entire app because you don't have access to InternalLibrary. This mechanism when you have a lot of nested dependencies 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 compilewith 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. Suggestion by Android Gradle plugin engineer Jerome Dochez (1)*)

• If you are a library mantainer 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.

REFERENCES (This is the same video splitted up for time saving)

Google I/O 2017 - How speed up Gradle builds (FULL VIDEO)

Google I/O 2017 - How speed up Gradle builds (NEW GRADLE PLUGIN 3.0.0 PART ONLY)

Google I/O 2017 - How speed up Gradle builds (reference to 1*)

Android documentation

share improve this answer

edited Dec 2 '17 at 18:03

JulianHarty

2,189 23 32

answered  Jun 7 '17 at 17:50

MatPag

8,859 5 33 48

• "Potentially a noob developer could have used the appcompat declared internally in your library instead of providing it's own dependency" Why would you declare the same dependency in multiple modules when all modules depend on a super module where you can define the dependency once? –  David  Jul 25 '17 at 16:58
• 1
  I noticed that api doesn't seem to work well in library modules. If I use it, I still can't access the dependencies from my app project. I can only access the code in that library itself. –  Allan W  Aug 1 '17 at 20:24
• This is fine and works on debug-builds but when using ProGuard (on release-versions) MyLibrary#myString() will crash because ProGuard will have InternalLibrary removed. What's the best-practice for android-libs to be used in ProGuard'ed apps? –  hardysim  Aug 23 '17 at 11:58
• 1
  I think the answer is not accurate, the application can use whatever scope it wants for the MyLibrary. It will see or not the InternalLibrary depending whether or not the MyLibrary uses api / implementation. –  Snicolas  Aug 24 '17 at 21:39
• 1
  thanks man. awesome explanation, much better than the one given in android's official docs –  Henry  May 15 at 17:57

show 5 more comments