Use api instead of compile for Android

[andrzejressel]

No description provided.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[JakeWharton]

The direct analogous is api. implementation is merely an optimization that should be opted into.

[andrzejressel]

I signed it!

[googlebot]

CLAs look good, thanks!

[jbduncan]

@JakeWharton I thought it was the other way round? Isn't implementation the same as compile, with api being the optimisation? :/

[jbduncan]

@JakeWharton Wait, I'm challenging myself now. I realise that I'm not 100% clear on the difference between api and implementation, so never mind. :)

[JakeWharton]

No. Compile transitively exposes the dependency on the classpath of downstream modules which is the same as api. Implementation hides the dependency. Of course Gradle doesn't enforce or validate any of this so it's a giant footgun unless you know what you're doing.

…

On Wed, May 23, 2018 at 5:06 PM Jonathan Bluett-Duncan < ***@***.***> wrote: @JakeWharton <https://github.com/JakeWharton> I thought it was the other way round? Isn't implementation the same as compile, with api being the optimisation? :/ — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3154 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEQr2oPYUNU7S_Elfe1CRqzOecLqzks5t1c9OgaJpZM4ULLig> .

[andrzejressel]

api it is then.

[cpovirk]

(Found https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation to back up Jake.)

[cpovirk]

Hmm, so should we change the JRE one to api, as well? It sounds like compile may be deprecated.

[JakeWharton]

I believe 'api' only exists for JRE projects if you're using the 'java-library' plugin. If you're using the regular 'java' plugin you only get 'compile' and 'implementation' (the idea being you're a leaf node and don't have anywhere to expose dependencies to).

…

On Wed, May 23, 2018 at 5:21 PM Chris Povirk ***@***.***> wrote: Hmm, so should we change the JRE one to api, as well? It sounds like compile may be deprecated. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3154 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEdtfVy2mpf-Lvk32inHC4veUluBBks5t1dLdgaJpZM4ULLig> .

[jbduncan]

@cpovirk compile is indeed deprecated. :)

[cpovirk]

Huh. So is the idea that Android projects are more likely to use the java-library plugin? If anything, I might have naively guessed they were less likely :) Is it just that the default Android build setup suggests java-library or something?

[JakeWharton]

Android projects use neither. API and implementation are available for all Android plugins for about a year now. The reason these PRs are sweeping the web is that they now wan when you use compile.

…

On Wed, May 23, 2018, 5:25 PM Chris Povirk ***@***.***> wrote: Huh. So is the idea that Android projects are more likely to use the java-library plugin? If anything, I might have naively guessed they were *less* likely :) Is it just that the default Android build setup suggests java-library or something? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3154 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEcpsROIWL_DcsNPdWgCua0QkTdbQks5t1dO6gaJpZM4ULLig> .

[cpovirk]

Ah! Thanks.

[jbduncan]

Hmm. It sounds to me that implementation is the most sensible default, and api should be used only if the java-library plugin is imported and the given project wants to expose Guava types to its users. Is my understanding correct @JakeWharton?

[JakeWharton]

Your understanding is correct because you understand the implications. Anyone who needs to look at the README to figure out how to add Guava beyond maybe just copy/pasting the coordinates will not have that understanding.

…

On Wed, May 23, 2018 at 5:35 PM Jonathan Bluett-Duncan < ***@***.***> wrote: Hmm. It sounds to me that implementation is the most sensible default, and api should be used only if the java-library plugin is imported *and* the given project wants to expose Guava types to its users. Is my understanding correct @JakeWharton <https://github.com/JakeWharton>? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3154 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEEEQZJ1WltcLH-FZJ78-iTVPVWmCWeks5t1dYogaJpZM4ULLig> .

[jbduncan]

@JakeWharton Cool! So you're suggesting api here because it's the most liberal option and most equivalent to the older compile, am I right?

[cpovirk]

(Even for people who don't expose Guava in their APIs, I'd be a little nervous about excluding transitive dependencies from the classpath, given problems with static analyzers and perhaps annotation processors discussed in #2824 and #2721. (There could also be problems if people use Guava annotations but don't consider that "exposing an API," but that seems less likely.) I suppose that those problems are relatively unlikely to affect people, though.)

[cpovirk]

Anyway, I do like the idea of suggesting the thing that is more likely to work (even if it's slower in some cases -- and I suspect only marginally so, since Guava isn't going to be changing between one build and the next). It is a little sad that this exports Guava to downstream targets, but that seems like the lesser evil (and no worse than what people see today).

One final thought: We could decide to give instructions for each of...

• Java 8+
• Java 7
• Android

...where the Java 7 instructions look like the current Android instructions and the Android instructions look like your new ones. But I'm not sure that's worth the potential confusion.

[jbduncan]

@cpovirk I think it's worth at least changing the remaining compile instruction for "guava-jre" to api, so that the Gradle installation instructions are consistent. :)

[cpovirk]

@jbduncan, @JakeWharton said above:

I believe 'api' only exists for JRE projects if you're using the
'java-library' plugin. If you're using the regular 'java' plugin you only
get 'compile' and 'implementation' (the idea being you're a leaf node and
don't have anywhere to expose dependencies to).

So I worry that api won't exist for some people, and they'll be confused.

Does Gradle warn about compile in JRE projects like it does in Android projects?

[jbduncan]

@cpovirk Good point about @JakeWharton's comment!

Gradle does warn about compile in JRE projects too. :(

Taking all this into consideration, I think the best advice to give Gradle users is something like the following:

To add a dependency using Gradle:

// For Java applications or Java libraries which use Guava internally:
implementation 'com.google.guava:guava:25.1-jre'
// Or, for Java libraries which use the "java-library" plugin and expose Guava types to users
api 'com.google.guava:guava:25.1-jre'
// Or, for Android applications & libraries which use Guava internally:
implementation 'com.google.guava:guava:25.1-android'
// Or, for Android libraries which use the "java-library" plugin and expose Guava types to users
api 'com.google.guava:guava:25.1-android'

But having said this, the example advice I give above is quite verbose. I wonder if there's a better way of presenting it to Gradle&Guava users...