Immutables: Update doc with how to configure Gradle (incl. so that it works in Eclipse & IntelliJ)

Created on 14 Dec 2018 · 8Comments · Source: immutables/immutables

I just tried to apply Immutables to a new project where I use Gradle 5.0.

https://immutables.github.io/getstarted.html#configuration-for-android suggests using com.android.tools.build:gradle and com.neenbedankt.gradle.plugins:android-apt but: (a) I doubt that is latest state of the art, (b) I'm not interested in Android, so that's a bit confusing anyway, (c) it anyway doesn't seem to work today (anymore), for me on Gradle 5.0. Here is what seems to do the trick, I can raise a PR with this once I've confirmed it works, if nobody chimes in having a better suggestion:

plugins {
    id 'java-library'
    id 'net.ltgt.apt' version '0.19'
    id 'net.ltgt.apt-eclipse' version '0.19'
    id 'net.ltgt.apt-idea' version '0.19'

dependencies { 
    apt "org.immutables:value:2.7.3"
    compileOnly "org.immutables:value:2.7.3:annotations"
    compileOnly "org.immutables:builder:2.7.3"
    compileOnly "org.immutables:gson:2.7.3:annotations"

BTW: In #804 there is WIP to Support Gradle Incremental Processing, this issue is only about doc as-is.

@elucash @tbroyer @oehme

Source

vorburger

👍5

Most helpful comment

I also want to know what is the current state of the art. Would be great if we can just list what works now[adays] so we can update the documentation.

For Maven:

either include the annotation processor as a projet dependency with <scope>provided</scope> (pros: subject to dependencyManagement, simpler/easier to drop in a project; cons: as with any provided dependency, classes are available at compile time but not runtime, this can cause issues with bundled/shaded dependencies depending on the naming scheme wrt IDE completion, and in some cases can cause dependency clashes, if bundled dependencies are not repackaged, or for transitive dependencies)
or use annotationProcessorPaths of maven-compiler-plugin 3.5+ (pros/cons: inverse from above)

I'd rather recommend the latter.
See https://github.com/google/dagger#maven as an example.

_IDE integration:_ recent versions of IntelliJ IDEA should automatically recognize annotationProcessorPaths and setup annotation processing accordingly. Eclipse with the m2e-apt plugin works rather well AFAICT (with the usual Eclipse caveats: only one annotation processing configuration for both main and test sources).

For Gradle:
Put the processor in annotationProcessor configuration for the source set you're compiling (e.g. testAnnotationProcessor for tests), and the annotations in api, implementation, or compileOnly. Outcome of the discussion in https://github.com/google/dagger/pull/1130 is that docs should use api, and document that when it doesn't exist (standard java projects, vs. Android or java-library projects) implementation should be used instead. There's nothing specific to Android projects anymore.

Also, pending Gradle 5.2 in a couple months from now, no -s is passed by default to javac, so generated sources end up next to compiled classes (and will be packaged in JARs). So I'd recommend using either the net.ltgt.apt plugin, or configuring options.annotationProcessorGeneratedSourcesDirectory manually on every JavaCompile task.

_IDE integration:_ it's rather bad for now (except possibly in Android Studio, I must admit I haven't tried). There are easy workarounds for IntelliJ IDEA, but Eclipse users will have to use the net.ltgt.apt-eclipse plugin for now. There's of course net.ltgt.apt-idea too that applies the workarounds automatically.

I'd suggest linking to the net.ltgt.apt README (https://github.com/tbroyer/gradle-apt-plugin) for all those issues above, I explain there what the plugin does (so you can choose whether to use it or not), and how to configure your project manually if you choose not to use the plugin. I also link to the various issues (in Gradle, Eclipse/Buildship, or IntelliJ IDEA) that the plugin works around so people can go vote for them.

tbroyer on 20 Dec 2018

🎉2

All 8 comments

apt "org.immutables:value:2.7.3"

or annotationProcessor "org.immutables:value:2.7.3", which one is recommended now?

vorburger on 14 Dec 2018

👍1

Hm, the config above actually still does not seem to automactially add build/generated/source/apt/main as source folder nor set the Java Compilier > Annotation Processing > Factory in Eclipse - normal?

vorburger on 14 Dec 2018

AFAICT, configuration should be identical for Android and non-Android projects using Gradle:

dependencies {
    annotationProcessor "org.immutables:value:2.7.3"
    api "org.immutables:value-annotations:2.7.3" // or implementation, or compileOnly
}

See discussion in https://github.com/google/dagger/pull/1130 about choosing the appropriate configuration for the annotations for your project.

Wrt IDE configuration for generated sources and/or annotation processing, see https://github.com/tbroyer/gradle-apt-plugin where I describe the situation. You can choose to use the net.ltgt.apt plugin (pick the one for your IDE), or configure things manually. But Eclipse is the poor relation of IDEs (mostly due to its own constraints).

Fwiw, the Maven snippet should probably suggest using <annotationProcessorPaths>:

<dependencies>
  <dependency>
    <groupId>org.immutables</groupId>
    <artifactId>value-annotations</artifactId>
    <version>2.7.3</version>
    <!-- see discussion above about whether to use scope=provided and/or optional=true here -->
  </dependency>
</dependencies>
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.0</version>
      <configuration>
        <annotationProcessorPaths>
          <path>
            <groupId>org.immutables</groupId>
            <artifactId>value</artifactId>
            <version>2.7.3</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>
  </plugins>
</build>

tbroyer on 14 Dec 2018

👍1

@tbroyer in the Maven example instead of org.immutables:value one can place org.immutables:value-processor inside annotationProcessorPaths; that dependency is slightly smaller. (But looks perfect otherwise :+1:)

Stephan202 on 15 Dec 2018

@Stephan202 @tbroyer perhaps one of you would like to raise a PR to this project for what you suggest to improve re. the Maven example? :smile: That way we could keep this issue focused :smiling_imp: on how to _Update doc with how to configure Gradle (incl. so that it works in Eclipse & IntelliJ)_ ...

AFAICT, configuration should be identical for Android and non-Android projects using Gradle:

wait, this is where I'm confused from the current as-is doc - is the buildscript with com.android.tools.build:gradle and com.neenbedankt.gradle.plugins:android-apt still needed? Even if one is not on Android? So we don't need to use your net.ltgt.apt anymore, only net.ltgt.apt-idea and/or net.ltgt.apt-eclipse ? Reading https://github.com/gradle/gradle/issues/4956 it seems that until Gradle v5.2 net.ltgt.apt is still useful? With Gradle _"recent"_ (v5.0? earlier?) is even com.android.tools.build:gradle and com.neenbedankt.gradle.plugins:android-apt not required anymore, JUST annotationProcessor "org.immutables:value:2.7.3" ? Sorry for double checking, this must be super obvious to you, but it seems to be worthwhile to clarify; then I can raise a PR to update the doc re. Gradle.

automactially add build/generated/source/apt/main as source folder nor set the Java Compilier > Annotation Processing > Factory in Eclipse

so does this work, if correctly configured? Like can you get proper incremental in-IDE build, or do you need to run the Gradle build on the CLI to get code re-generated? It somehow did not work for me when I tried yesterday.

api "org.immutables:value-annotations:2.7.3" // or implementation, or compileOnly

just about this point: The compileOnly seems most sane for an only build time annotation, agreed?

vorburger on 15 Dec 2018

I also want to know what is the current state of the art. Would be great if we can just list what works now[adays] so we can update the documentation.

WRT org.immutables:value-processor is actually "less" recommended to the general audience and actually "bigger" if you think: it drags some amount of transitive dependencies, which are not minified and can conflict with some other annotation processors (if they share the same problem)

elucash on 19 Dec 2018

org.immutables:value-processor is actually "less" recommended to the general audience and actually "bigger" if you think: it drags some amount of transitive dependencies, which are not minified and can conflict with some other annotation processors

Ah, good point. That reminds me of google/error-prone#1176.

Stephan202 on 20 Dec 2018

I also want to know what is the current state of the art. Would be great if we can just list what works now[adays] so we can update the documentation.

For Maven:

either include the annotation processor as a projet dependency with <scope>provided</scope> (pros: subject to dependencyManagement, simpler/easier to drop in a project; cons: as with any provided dependency, classes are available at compile time but not runtime, this can cause issues with bundled/shaded dependencies depending on the naming scheme wrt IDE completion, and in some cases can cause dependency clashes, if bundled dependencies are not repackaged, or for transitive dependencies)
or use annotationProcessorPaths of maven-compiler-plugin 3.5+ (pros/cons: inverse from above)

I'd rather recommend the latter.
See https://github.com/google/dagger#maven as an example.