From e8740a50d2f2221a572d86166bab96055c46c6d6 Mon Sep 17 00:00:00 2001 From: Dean Wette Date: Tue, 14 Nov 2023 13:02:46 -0600 Subject: [PATCH 1/3] docs - Gradle plugin adds annotation processors automatically, and automatic dependencies can be suppressed alternatively. closes #870 --- src/docs/asciidoc/index.adoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index 147018da..c63bfdb6 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -306,6 +306,17 @@ The https://plugins.gradle.org/plugin/io.micronaut.library[Micronaut library plu * Applies the https://search.maven.org/artifact/io.micronaut.platform/micronaut-platform[Micronaut Bill of Materials (BOM)] * Applies the `java-library` plugin * Configures annotation processing for the current language (Groovy, Java or Kotlin) +* Adds annotation processors automatically for Micronaut modules +** `io.micronaut.data:micronaut-data-processor` +** `io.micronaut.jaxrs:micronaut-jaxrs-processor` +** `io.micronaut.micrometer:micronaut-micrometer-annotation` +** `io.micronaut.microstream:micronaut-microstream-annotations` +** `io.micronaut.openapi:micronaut-openapi` +** `io.micronaut.security:micronaut-security-annotations` +** `io.micronaut.serde:micronaut-serde-processor` +** `io.micronaut.spring:micronaut-spring-annotation` +** `io.micronaut.tracing:micronaut-tracing-annotation` +** `io.micronaut.validation:micronaut-validation-processor` The `micronaut` DSL can be used to configure how this behaves. @@ -320,6 +331,9 @@ micronaut { // will not be automatically applied, and you will have to add it yourself // to your dependencies, or specify versions of Micronaut modules explicitly importMicronautPlatform = true + // In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. + // This should be rare but it is possible to suppress these, as follows: + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") processing { // Sets whether incremental annotation processing is enabled incremental true @@ -343,6 +357,18 @@ micronaut { } } ---- +In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user. + +.Suppressing automatic dependencies +[source, groovy, subs="verbatim,attributes", role="multi-language-sample"] +---- +micronaut { + // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, + // a dependency shouldn't be automatically added, you can add its coordinates to this set. + // The format is "group:name". It must not include the version. + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") +} +---- [source, kotlin, subs="verbatim,attributes", role="multi-language-sample"] ---- From 320a5b5f91b7ae3e555dcaf677b43e4a2158b966 Mon Sep 17 00:00:00 2001 From: Dean Wette Date: Tue, 14 Nov 2023 13:18:38 -0600 Subject: [PATCH 2/3] fix example formatting --- src/docs/asciidoc/index.adoc | 38 ++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index c63bfdb6..458d89ad 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -331,9 +331,6 @@ micronaut { // will not be automatically applied, and you will have to add it yourself // to your dependencies, or specify versions of Micronaut modules explicitly importMicronautPlatform = true - // In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. - // This should be rare but it is possible to suppress these, as follows: - ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") processing { // Sets whether incremental annotation processing is enabled incremental true @@ -357,18 +354,6 @@ micronaut { } } ---- -In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user. - -.Suppressing automatic dependencies -[source, groovy, subs="verbatim,attributes", role="multi-language-sample"] ----- -micronaut { - // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, - // a dependency shouldn't be automatically added, you can add its coordinates to this set. - // The format is "group:name". It must not include the version. - ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") -} ----- [source, kotlin, subs="verbatim,attributes", role="multi-language-sample"] ---- @@ -402,6 +387,29 @@ micronaut { } ---- +In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user. + +.Suppressing automatic dependencies +[source, groovy, subs="verbatim,attributes", role="multi-language-sample"] +---- +micronaut { + // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, + // a dependency shouldn't be automatically added, you can add its coordinates to this set. + // The format is "group:name". It must not include the version. + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") +} +---- + +[source, kotlin, subs="verbatim,attributes", role="multi-language-sample"] +---- +micronaut { + // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, + // a dependency shouldn't be automatically added, you can add its coordinates to this set. + // The format is "group:name". It must not include the version. + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") +} +---- + NOTE: The Micronaut Library plugin also supports Groovy and Kotlin sources. === Kotlin Support From 7ffd99196408d9342f5cb4b5026a4e9e909d6bc4 Mon Sep 17 00:00:00 2001 From: Dean Wette Date: Wed, 15 Nov 2023 10:36:25 -0600 Subject: [PATCH 3/3] Add section to explain automatic annotation processors. --- src/docs/asciidoc/index.adoc | 82 +++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 34 deletions(-) diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index 458d89ad..1a9628ae 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -306,17 +306,7 @@ The https://plugins.gradle.org/plugin/io.micronaut.library[Micronaut library plu * Applies the https://search.maven.org/artifact/io.micronaut.platform/micronaut-platform[Micronaut Bill of Materials (BOM)] * Applies the `java-library` plugin * Configures annotation processing for the current language (Groovy, Java or Kotlin) -* Adds annotation processors automatically for Micronaut modules -** `io.micronaut.data:micronaut-data-processor` -** `io.micronaut.jaxrs:micronaut-jaxrs-processor` -** `io.micronaut.micrometer:micronaut-micrometer-annotation` -** `io.micronaut.microstream:micronaut-microstream-annotations` -** `io.micronaut.openapi:micronaut-openapi` -** `io.micronaut.security:micronaut-security-annotations` -** `io.micronaut.serde:micronaut-serde-processor` -** `io.micronaut.spring:micronaut-spring-annotation` -** `io.micronaut.tracing:micronaut-tracing-annotation` -** `io.micronaut.validation:micronaut-validation-processor` +* <<#sec:automatic-annotation-processors, Adds annotation processors automatically>> for Micronaut modules The `micronaut` DSL can be used to configure how this behaves. @@ -387,29 +377,6 @@ micronaut { } ---- -In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user. - -.Suppressing automatic dependencies -[source, groovy, subs="verbatim,attributes", role="multi-language-sample"] ----- -micronaut { - // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, - // a dependency shouldn't be automatically added, you can add its coordinates to this set. - // The format is "group:name". It must not include the version. - ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") -} ----- - -[source, kotlin, subs="verbatim,attributes", role="multi-language-sample"] ----- -micronaut { - // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, - // a dependency shouldn't be automatically added, you can add its coordinates to this set. - // The format is "group:name". It must not include the version. - ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") -} ----- - NOTE: The Micronaut Library plugin also supports Groovy and Kotlin sources. === Kotlin Support @@ -1966,6 +1933,52 @@ micronaut { In addition, it exposes a `openApiGenerator` configuration which can be used to declare additional dependencies to put on the generator classpath. This can be useful in case you want to implement your own generators, in which case you will also have to implement custom tasks which extend the link:api/io/micronaut/gradle/openapi/tasks/AbstractOpenApiGenerator.html[AbstractOpenApiGenerator task type]. +[[additional-notes]] +== Additional Notes + +[[sec:automatic-annotation-processors]] +=== Automatic annotationProcessor dependencies + +When the plugin detects you have a dependency with a group id corresponding to a known annotation processor for it, it adds the annotation processor automatically. The following annotation processors are currently supported by this feature. + +* `io.micronaut.data:micronaut-data-processor` +* `io.micronaut.jaxrs:micronaut-jaxrs-processor` +* `io.micronaut.micrometer:micronaut-micrometer-annotation` +* `io.micronaut.microstream:micronaut-microstream-annotations` +* `io.micronaut.openapi:micronaut-openapi` +* `io.micronaut.security:micronaut-security-annotations` +* `io.micronaut.serde:micronaut-serde-processor` +* `io.micronaut.spring:micronaut-spring-annotation` +* `io.micronaut.tracing:micronaut-tracing-annotation` +* `io.micronaut.validation:micronaut-validation-processor` + +[[sec:suppress-automatic-dependencies]] +=== Suppressing automatic dependencies + +In some circumstances, automatic dependencies – e.g. annotation processors listed above – can get in the way. This should be rare, but it is possible to suppress them, as follows. It has no default and using suppression shifts responsibility of adding the dependencies to the user. + +.Suppressing automatic dependencies +[source, groovy, subs="verbatim,attributes", role="multi-language-sample"] +---- +micronaut { + // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, + // a dependency shouldn't be automatically added, you can add its coordinates to this set. + // The format is "group:name". It must not include the version. + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") +} +---- + +[source, kotlin, subs="verbatim,attributes", role="multi-language-sample"] +---- +micronaut { + // The Micronaut plugins can automatically add dependencies to your project. If, for some reason, + // a dependency shouldn't be automatically added, you can add its coordinates to this set. + // The format is "group:name". It must not include the version. + ignoredAutomaticDependencies.add("io.micronaut.data:micronaut-data-processor") +} +---- + + == Upgrade notes === Upgrading from 2.x @@ -2005,3 +2018,4 @@ In addition, the official GraalVM plugin makes use of Gradle toolchains support, then we recommend tweaking toolchain detection as described in <<#toolchain-behavior, this section of the documentation>>. In any case, make sure to follow the <<#native-image,configuration instructions>>. +