Design doc for better/built-in Java annotation processing support

[tbroyer]

Superseeds #431

/cc @alkemist

[tbroyer]

This image is intended to eventually replace subprojects/docs/src/docs/userguide/img/javaPluginConfigurations.graphml in the user guide.

[breskeby]

Hey Thomas,
We finally have the bandwith to deal better with community contributions like this. With 2.12 there will be a 'compileOnly' dependency that can be used for annotation processing. If you're still interested to work on this, please let us know.

[tbroyer]

With 2.12 there will be a 'compileOnly' dependency that can be used for annotation processing.

Oh great! Looks a lot like what I do in net.ltgt.apt plugin

If you're still interested to work on this, please let us know.

Yes sure. How should we start? Do you want me to first update this PR taking into account the compileOnly/testCompileOnly that are already in? (possibly just marking them as already committed).

[breskeby]

For now I would update the design doc to reflect that we have now compileOnly dependencies. The test coverage should also contain integration tests to ensure we don't break anything regarding the current behaviour. Would you mind prefixing the different stories in the spec with Story -. That makes it easier to follow in my opinion. I think we can all agree that having these additional compiler options available for dealing with annotations. I'm just not sure yet if we should have an additional default configuration coming with the java plugin for annotation processors. This brings some overhead to EVERY java projects.
With having compileOnly now available compile time only annotation processing does work with reasonable defaults.
I saw you have also provided a first implementation with #450. I'll comment on this separately.

[tbroyer]

Updated, also added a few things (used separate commits to make reviewing changes easier; tell me if you'd prefer I squash commits instead)

I'm just not sure yet if we should have an additional default configuration coming with the java plugin for annotation processors. This brings some overhead to EVERY java projects.

The reason is that you don't want annotation processor dependencies to mess with your project's dependencies, and end up with things that compile but don't run (hopefully fail tests, but that depends on test coverage).
There are annotation processors that look at what's in the classpath too to decide what to do (e.g. Immutables.org would default to using Guava collections if available in the classpath, and JDK collections with Collections.unmodifiableXxx otherwise; if another annotation processor brings Guava, that would affect the behavior of Immutables.org).
This can be avoided by clearly separating the processorpath from the compile classpath.

See google/dagger#228 and google/auto#268

That could probably be left to plugins though (such as android-apt and net.ltgt.apt); in this case, that could still be described here with a note that it won't be implemented, right?

[breskeby]

This looks quite good to me. Yes I think we can just put a note on the stories which we probably no want in gradle core. Two minor remarks before I'll merge your stuff

1. is there any integration test missing from your point of view? I saw you have a todo in the spec
2. could you add a dedicated API section about the changes on the compile options. see https://github.com/gradle/gradle/tree/master/design-docs/features/ide-integration/source-and-target-jvm#story---expose-natures-and-builders-for-projects for example. many thanks!

[tbroyer]

is there any integration test missing from your point of view? I saw you have a todo in the spec

Well, actually, no. I believe described unit tests would be enough for the rest here (but, well, I also believed they were enough by themselves, without even integration tests, so…)

could you add a dedicated API section about the changes on the compile options. see https://github.com/gradle/gradle/tree/master/design-docs/features/ide-integration/source-and-target-jvm#story---expose-natures-and-builders-for-projects for example. many thanks!

Done.

PTAL

[breskeby]

Hey,
I merged this pull request manually and did some minor tweaks to the spec. thanks for the contribution!

[tbroyer]

Thanks. What would be the next step then? Updating #450?

[breskeby]

yes. I think so.