From 019dd43397fe071a03661f71d6601b720d7cb8ae Mon Sep 17 00:00:00 2001 From: Thomas Canava Date: Mon, 6 Jan 2025 21:30:49 +0100 Subject: [PATCH] docs: Improve gradle docs by adding kotlin snippets --- docs/src/main/asciidoc/aws-lambda.adoc | 20 +++ .../asciidoc/building-my-first-extension.adoc | 166 ++++++++++++++++-- docs/src/main/asciidoc/cassandra.adoc | 13 ++ .../asciidoc/grpc-service-implementation.adoc | 15 ++ .../asciidoc/infinispan-client-reference.adoc | 6 +- docs/src/main/asciidoc/infinispan-client.adoc | 4 +- .../asciidoc/kafka-schema-registry-avro.adoc | 84 ++++++++- .../kafka-schema-registry-json-schema.adoc | 85 ++++++++- docs/src/main/asciidoc/logging.adoc | 7 +- .../security-openid-connect-client.adoc | 5 +- .../main/asciidoc/tests-with-coverage.adoc | 81 +++++++++ .../src/main/asciidoc/writing-extensions.adoc | 26 ++- 12 files changed, 485 insertions(+), 27 deletions(-) diff --git a/docs/src/main/asciidoc/aws-lambda.adoc b/docs/src/main/asciidoc/aws-lambda.adoc index ec05de3639b8b..e56660372f16b 100644 --- a/docs/src/main/asciidoc/aws-lambda.adoc +++ b/docs/src/main/asciidoc/aws-lambda.adoc @@ -286,6 +286,9 @@ for your lambda deployment. Example Gradle dependencies: +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** [source,groovy] ---- dependencies { @@ -297,6 +300,23 @@ dependencies { testImplementation 'io.rest-assured:rest-assured' } ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +dependencies { + implementation(enforcedPlatform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}")) + implementation("io.quarkus:quarkus-resteasy") + implementation("io.quarkus:quarkus-amazon-lambda") + + testImplementation("io.quarkus:quarkus-junit5") + testImplementation("io.rest-assured:rest-assured") +} +---- +**** == Live Coding and Unit/Integration Testing diff --git a/docs/src/main/asciidoc/building-my-first-extension.adoc b/docs/src/main/asciidoc/building-my-first-extension.adoc index e61f80b010a27..7f1406c41eb68 100644 --- a/docs/src/main/asciidoc/building-my-first-extension.adoc +++ b/docs/src/main/asciidoc/building-my-first-extension.adoc @@ -404,9 +404,14 @@ As mentioned before, an extension is composed of two modules: * `runtime` * `deployment` -We are going to create a Gradle multi-module project with those two modules. Here is a simple `settings.gradle` example file: +We are going to create a Gradle multi-module project with those two modules. -[source, groovy] +Here is a simple `settings.gradle` example file: + +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy,subs=attributes+] ---- pluginManagement { repositories { @@ -414,7 +419,7 @@ pluginManagement { gradlePluginPortal() } plugins { - id 'io.quarkus.extension' version "${quarkus.version}" <1> + id 'io.quarkus.extension' version "{quarkus-version}" <1> } } @@ -422,13 +427,43 @@ include 'runtime', 'deployment' <2> rootProject.name = 'greeting-extension' ---- +**** <1> Configure the quarkus extension plugin version <2> Include both `runtime` and `deployment` modules +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin,subs=attributes+] +---- +pluginManagement { + repositories { + mavenCentral() + gradlePluginPortal() + } + plugins { + id("io.quarkus.extension") version "{quarkus-version}" <1> + } +} + +include("runtime", "deployment") <2> + +rootProject.name = "greeting-extension" +---- +**** + +<1> Configure the quarkus extension plugin version +<2> Include both `runtime` and `deployment` modules + +NOTE: For kotlin add the `.kts` extension the build files, for example: `settings.gradle.kts` + Here is a sample of a root `build.gradle` file: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] ---- subprojects { apply plugin: 'java-library' <1> @@ -438,6 +473,26 @@ subprojects { version '1.0-SNAPSHOT' } ---- +**** + +<1> Apply the `java-library` plugin for all sub-modules +<2> Apply the `maven-publish` plugin used to publish our artifacts +<3> Globally set the group id used for publication + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +subprojects { + apply(plugin = "java-library") // <1> + apply(plugin = "maven-publish") // <2> + + group = "org.acme" <3> + version = "1.0-SNAPSHOT" +} +---- +**** <1> Apply the `java-library` plugin for all sub-modules <2> Apply the `maven-publish` plugin used to publish our artifacts @@ -449,24 +504,44 @@ The plugin will *only* be applied to the `runtime` module. ==== The deployment module The deployment module does not require any specific plugin. -Here is an example of a minimal `build.gradle` file for the `deployment` module: +Here is an example of a minimal gradle build file for the `deployment` module: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy,subs=attributes+] ---- name = 'greeting-extension-deployment' <1> dependencies { implementation project(':runtime') <2> - - implementation platform("io.quarkus:quarkus-bom:${quarkus.version}") - + implementation 'io.quarkus:quarkus-arc-deployment' + implementation platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}") testImplementation 'io.quarkus:quarkus-junit5-internal' } ---- +**** <1> By convention, the deployment module has the `-deployment` suffix (`greeting-extension-deployment`). <2> The deployment module *must* depend on the `runtime` module. +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin,subs=attributes+] +---- + +dependencies { + implementation(project(":runtime")) <1> + implementation("io.quarkus:quarkus-arc-deployment") + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) + testImplementation("io.quarkus:quarkus-junit5-internal") +} +---- +**** + +<1> The deployment module *must* depend on the `runtime` module. + ==== The runtime module The runtime module applies the `io.quarkus.extension` plugin. This will: @@ -476,7 +551,10 @@ The runtime module applies the `io.quarkus.extension` plugin. This will: Here is an example of `build.gradle` file for the `runtime` module: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy,subs=attributes+] ---- plugins { id 'io.quarkus.extension' <1> @@ -486,13 +564,33 @@ name = 'greeting-extension' <2> description = 'Greeting extension' dependencies { - implementation platform("io.quarkus:quarkus-bom:${quarkus.version}") + implementation platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}") } ---- +**** <1> Apply the `io.quarkus.extension` plugin. <2> By convention, the runtime module doesn't have a suffix (and thus is named `greeting-extension`) as it is the artifact exposed to the end user. +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin,subs=attributes+] +---- +plugins { + id("io.quarkus.extension") // <1> +} + +description = "Greeting extension" + +dependencies { + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) +} +---- +**** + +<1> Apply the `io.quarkus.extension` plugin. + == Basic version of the Sample Greeting extension === Implementing the Greeting feature @@ -515,10 +613,23 @@ All we need to do is add `quarkus-undertow` as dependency to our `./greeting-ext For Gradle, add the dependency in `./greeting-extension/runtime/build.gradle` file: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] ---- implementation 'io.quarkus:quarkus-undertow' ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- + implementation("io.quarkus:quarkus-undertow") +---- +**** NOTE: The dependency on `quarkus-arc` generated by the `create-extension` mojo can now be removed since `quarkus-undertow` already depends on it. @@ -620,10 +731,23 @@ NOTE: The dependency on `quarkus-arc-deployment` generated by the `create-extens For Gradle, add the dependency in `./greeting-extension/deployment/build.gradle` file: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] ---- implementation 'io.quarkus:quarkus-undertow-deployment' ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- + implementation("io.quarkus:quarkus-undertow-deployment") +---- +**** We can now update `org.acme.greeting.extension.deployment.GreetingExtensionProcessor`: @@ -683,11 +807,25 @@ Let's add the `rest-assured` dependency into the `./greeting-extension/deployme For Gradle, add the dependency in `./greeting-extension/deployment/build.gradle` file: -[source, groovy] +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** +[source,groovy] ---- ... testImplementation 'io.rest-assured:rest-assured' ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- + ... + testImplementation("io.rest-assured:rest-assured") +---- +**** The `create-extension` Maven Mojo can create the test and integration-test structure (drop the `-DwithoutTests`). Here, we'll create it ourselves: diff --git a/docs/src/main/asciidoc/cassandra.adoc b/docs/src/main/asciidoc/cassandra.adoc index 42cb2c8ba61f0..cffc2efb28209 100644 --- a/docs/src/main/asciidoc/cassandra.adoc +++ b/docs/src/main/asciidoc/cassandra.adoc @@ -187,10 +187,23 @@ by modifying the compiler plugin configuration in the project's `pom.xml` file a With Gradle, this is done by adding the following line to the `build.gradle` file: +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** [source,groovy] ---- annotationProcessor "com.datastax.oss.quarkus:cassandra-quarkus-mapper-processor:${cassandra-quarkus.version}" ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +annotationProcessor("com.datastax.oss.quarkus:cassandra-quarkus-mapper-processor:${cassandra-quarkus.version}") +---- +**** IMPORTANT: Verify that you are enabling the right annotation processor! The Cassandra driver ships with its Object Mapper annotation processor, called `java-driver-mapper-processor`. But the diff --git a/docs/src/main/asciidoc/grpc-service-implementation.adoc b/docs/src/main/asciidoc/grpc-service-implementation.adoc index 3715e45c0063a..996c0faf081e5 100644 --- a/docs/src/main/asciidoc/grpc-service-implementation.adoc +++ b/docs/src/main/asciidoc/grpc-service-implementation.adoc @@ -381,12 +381,27 @@ Having it, you can run the dev mode with: `mvn quarkus:dev -Pdevelopment`. If you use Gradle, you can simply add a dependency for the `quarkusDev` task: +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** [source,groovy] ---- dependencies { quarkusDev 'io.quarkus:quarkus-vertx-http' } ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin] +---- +dependencies { + quarkusDev("io.quarkus:quarkus-vertx-http") +} +---- +**** == gRPC Server metrics diff --git a/docs/src/main/asciidoc/infinispan-client-reference.adoc b/docs/src/main/asciidoc/infinispan-client-reference.adoc index 7084c2e4ae3d9..9181284ef67f1 100644 --- a/docs/src/main/asciidoc/infinispan-client-reference.adoc +++ b/docs/src/main/asciidoc/infinispan-client-reference.adoc @@ -38,11 +38,11 @@ This command adds the following dependency to your build file: ---- -[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] +[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle",subs=attributes+] .build.gradle ---- -implementation 'io.quarkus:quarkus-infinispan-client' -annotationProcessor 'org.infinispan.protostream:protostream-processor:{infinispan-protostream-version}' <1> +implementation("io.quarkus:quarkus-infinispan-client") +annotationProcessor("org.infinispan.protostream:protostream-processor:{infinispan-protostream-version}") <1> ---- <1> Mandatory in the Gradle build to enable the generation of the files in the annotation based serialization diff --git a/docs/src/main/asciidoc/infinispan-client.adoc b/docs/src/main/asciidoc/infinispan-client.adoc index f09acc688c08d..cfc3f062e02f6 100644 --- a/docs/src/main/asciidoc/infinispan-client.adoc +++ b/docs/src/main/asciidoc/infinispan-client.adoc @@ -59,11 +59,11 @@ This will add the following to your build file: ---- -[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] +[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle",subs=attributes+] .build.gradle ---- implementation("io.quarkus:quarkus-infinispan-client") -annotationProcessor 'org.infinispan.protostream:protostream-processor:4.6.1.Final' <1> +annotationProcessor("org.infinispan.protostream:protostream-processor:{infinispan-protostream-version}") <1> ---- <1> Mandatory in the Gradle build to enable the generation of the files in the annotation based serialization diff --git a/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc b/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc index 4985e3195a79b..b3f79a44698f5 100644 --- a/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc +++ b/docs/src/main/asciidoc/kafka-schema-registry-avro.adoc @@ -433,6 +433,13 @@ testImplementation("io.quarkus:quarkus-rest-client") testImplementation("org.awaitility:awaitility") ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +testImplementation("io.quarkus:quarkus-rest-client") +testImplementation("org.awaitility:awaitility") +---- + In the test, we will send movies in a loop and check if the `ConsumedMovieResource` returns what we send. @@ -564,6 +571,14 @@ testImplementation("io.strimzi:strimzi-test-container:0.105.0") { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +testImplementation("io.strimzi:strimzi-test-container:0.105.0") { + exclude(group = "org.apache.logging.log4j", module = "log4j-core") +} +---- + [source,java] ---- package org.acme.kafka; @@ -687,7 +702,7 @@ and the REST client `apicurio-common-rest-client-vertx` dependency are set to co .build.gradle ---- dependencies { - implementation(platform("{quarkus-platform-groupid}:quarkus-bom:2.12.3.Final")) + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) ... @@ -718,6 +733,41 @@ dependencies { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin",subs=attributes+] +.build.gradle.kts +---- +dependencies { + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) + + ... + + implementation("io.quarkus:quarkus-apicurio-registry-avro") + implementation("io.apicurio:apicurio-registry-serdes-avro-serde") { + exclude(group = "io.apicurio", module = "apicurio-common-rest-client-jdk") + exclude(group = "io.apicurio", module = "apicurio-registry-client") + exclude(group = "io.apicurio", module = "apicurio-registry-common") + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-registry-client") { + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-registry-common") { + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-common-rest-client-vertx") { + version { + strictly("0.1.5.Final") + } + } +} +---- + Known previous compatible versions for `apicurio-registry-client` and `apicurio-common-rest-client-vertx` are the following - `apicurio-registry-client` 2.1.5.Final with `apicurio-common-rest-client-vertx` 0.1.5.Final @@ -794,6 +844,31 @@ dependencies { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +repositories { + ... + + maven { + url = uri("https://packages.confluent.io/maven/") + } +} + +dependencies { + ... + + implementation("io.quarkus:quarkus-confluent-registry-avro") + + // Confluent registry libraries use Jakarta REST client + implementation("io.quarkus:quarkus-rest-client") + + implementation("io.confluent:kafka-avro-serializer:7.2.0") { + exclude(group = "jakarta.ws.rs", module = "jakarta.ws.rs-api") + } +} +---- + In JVM mode, any version of `io.confluent:kafka-avro-serializer` can be used. In native mode, Quarkus supports the following versions: `6.2.x`, `7.0.x`, `7.1.x`, `7.2.x`, `7.3.x`. @@ -814,6 +889,13 @@ dependencies { implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-csv") } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +dependencies { + implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-csv") +} +---- For any other versions, the native configuration may need to be adjusted. diff --git a/docs/src/main/asciidoc/kafka-schema-registry-json-schema.adoc b/docs/src/main/asciidoc/kafka-schema-registry-json-schema.adoc index 55f97aec25670..435028c641ca9 100644 --- a/docs/src/main/asciidoc/kafka-schema-registry-json-schema.adoc +++ b/docs/src/main/asciidoc/kafka-schema-registry-json-schema.adoc @@ -461,6 +461,13 @@ testImplementation("io.quarkus:quarkus-rest-client") testImplementation("org.awaitility:awaitility") ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +testImplementation("io.quarkus:quarkus-rest-client") +testImplementation("org.awaitility:awaitility") +---- + In the test, we will send movies in a loop and check if the `ConsumedMovieResource` returns what we send. @@ -592,6 +599,14 @@ testImplementation("io.strimzi:strimzi-test-container:0.105.0") { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +testImplementation("io.strimzi:strimzi-test-container:0.105.0") { + exclude(group = "org.apache.logging.log4j", module = "log4j-core") +} +---- + [source,java] ---- package org.acme.kafka; @@ -715,7 +730,7 @@ and the REST client `apicurio-common-rest-client-vertx` dependency are set to co .build.gradle ---- dependencies { - implementation(platform("{quarkus-platform-groupid}:quarkus-bom:2.12.3.Final")) + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) ... @@ -746,6 +761,41 @@ dependencies { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin",subs=attributes+] +.build.gradle.kts +---- +dependencies { + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) + + ... + + implementation("io.quarkus:quarkus-apicurio-registry-json-schema") + implementation("io.apicurio:apicurio-registry-serdes-json-schema-serde") { + exclude(group = "io.apicurio", module = "apicurio-common-rest-client-jdk") + exclude(group = "io.apicurio", module = "apicurio-registry-client") + exclude(group = "io.apicurio", module = "apicurio-registry-common") + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-registry-client") { + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-registry-common") { + version { + strictly("2.1.5.Final") + } + } + implementation("io.apicurio:apicurio-common-rest-client-vertx") { + version { + strictly("0.1.5.Final") + } + } +} +---- + Known previous compatible versions for `apicurio-registry-client` and `apicurio-common-rest-client-vertx` are the following - `apicurio-registry-client` 2.1.5.Final with `apicurio-common-rest-client-vertx` 0.1.5.Final @@ -822,6 +872,31 @@ dependencies { } ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +repositories { + ... + + maven { + url = uri("https://packages.confluent.io/maven/") + } +} + +dependencies { + ... + + implementation("io.quarkus:quarkus-confluent-registry-json-schema") + + // Confluent registry libraries use Jakarta REST client + implementation("io.quarkus:quarkus-rest-client") + + implementation("io.confluent:kafka-json-schema-serializer:7.2.0") { + exclude(group = "jakarta.ws.rs", module = "jakarta.ws.rs-api") + } +} +---- + In JVM mode, any version of `io.confluent:kafka-json-schema-serializer` can be used. In native mode, Quarkus supports the following versions: `6.2.x`, `7.0.x`, `7.1.x`, `7.2.x`, `7.3.x`. @@ -842,7 +917,13 @@ dependencies { implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-csv") } ---- - +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +dependencies { + implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-csv") +} +---- For any other versions, the native configuration may need to be adjusted. diff --git a/docs/src/main/asciidoc/logging.adoc b/docs/src/main/asciidoc/logging.adoc index 1a50a862618b0..7c02902b1f173 100644 --- a/docs/src/main/asciidoc/logging.adoc +++ b/docs/src/main/asciidoc/logging.adoc @@ -701,10 +701,11 @@ The system property must be set early on to be effective, so it is recommended t For Gradle, add the following configuration to the `build.gradle` file: -[source, groovy] + +[source,groovy] ---- -test { - systemProperty "java.util.logging.manager", "org.jboss.logmanager.LogManager" +tasks.test { + systemProperty("java.util.logging.manager", "org.jboss.logmanager.LogManager") } ---- diff --git a/docs/src/main/asciidoc/security-openid-connect-client.adoc b/docs/src/main/asciidoc/security-openid-connect-client.adoc index 0f9e86fafa940..400ff19cc6fb8 100644 --- a/docs/src/main/asciidoc/security-openid-connect-client.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-client.adoc @@ -106,7 +106,10 @@ It adds the following extensions to your build file: [source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] .build.gradle ---- -implementation("io.quarkus:quarkus-oidc,rest-client-oidc-filter,rest-client-oidc-token-propagation,rest") +implementation("io.quarkus:quarkus-oidc") +implementation("io.quarkus:quarkus-oidc-rest-client-oidc-filter") +implementation("io.quarkus:quarkus-oidc-rest-client-oidc-token-propagation") +implementation("io.quarkus:quarkus-rest") ---- == Writing the application diff --git a/docs/src/main/asciidoc/tests-with-coverage.adoc b/docs/src/main/asciidoc/tests-with-coverage.adoc index d1bceb1b2b423..769477f0324b8 100644 --- a/docs/src/main/asciidoc/tests-with-coverage.adoc +++ b/docs/src/main/asciidoc/tests-with-coverage.adoc @@ -164,6 +164,11 @@ Now we need to add JaCoCo to our project. To do this we need to add the followin ---- testImplementation("io.quarkus:quarkus-jacoco") ---- +[source,gradle-kotlin,role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +---- +testImplementation("io.quarkus:quarkus-jacoco") +---- This Quarkus extension takes care of everything that would usually be done via the JaCoCo Maven plugin, so no additional config is required. @@ -270,6 +275,31 @@ test { <2> This config tells it to ignore `@QuarkusTest` related classes, as they are loaded by `QuarkusClassLoader` <3> Set this config to `false` if you are also using the `quarkus-jacoco` extension and have at least one `@QuarkusTest`. The default `jacocoTestReport` task can be skipped since `quarkus-jacoco` will generate the combined report of regular unit tests and `@QuarkusTest` classes since the execution data is recorded in the same file. **** +[role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +**** +[source,gradle-kotlin,subs=attributes+] +---- +plugins { + jacoco // <1> +} + +tasks.test { + finalizedBy(tasks.jacocoTestReport) + extensions.configure(JacocoTaskExtension::class) { + excludeClassLoaders = listOf("*QuarkusClassLoader") // <2> + destinationFile = layout.buildDirectory.file("jacoco-quarkus.exec").get().asFile // <2> + } +} + +tasks.jacocoTestReport { + enabled = false // <3> +} +---- +<1> Add the `jacoco` gradle plugin +<2> This config tells it to ignore `@QuarkusTest` related classes, as they are loaded by `QuarkusClassLoader` +<3> Set this config to `false` if you are also using the `quarkus-jacoco` extension and have at least one `@QuarkusTest`. The default `jacocoTestReport` task can be skipped since `quarkus-jacoco` will generate the combined report of regular unit tests and `@QuarkusTest` classes since the execution data is recorded in the same file. +**** WARNING: This config will only work if at least one `@QuarkusTest` is being run. If you are not using `@QuarkusTest` then you can simply use the JaCoCo plugin in the standard manner with no additional config. @@ -467,6 +497,57 @@ jacocoTestCoverageVerification { <3> Exclude all classes in `org/example/package` package **** +[role="secondary asciidoc-tabs-target-sync-gradle-kotlin"] +.build.gradle.kts +**** +[source, gradle-kotlin] +---- +tasks.jacocoTestCoverageVerification { + executionData.setFrom("${layout.buildDirectory.get()}/jacoco-quarkus.exec") + violationRules { + rule { + limit { + counter = "INSTRUCTION" + value = "COVEREDRATIO" + minimum = 0.80.toBigDecimal() + } + limit { + counter = "BRANCH" + value = "COVEREDRATIO" + minimum = 0.72.toBigDecimal() + } + } + } +} + +tasks.check { + dependsOn(tasks.jacocoTestCoverageVerification) +} +---- + +Excluding classes from the verification task can be configured as following: + +[source,gradle-kotlin] +---- +afterEvaluate { // <1> + tasks.jacocoTestCoverageVerification { + classDirectories.setFrom(classDirectories.files.flatMap { // <2> + fileTree(it) { + exclude( + listOf( + "org/example/package/**/*" // <3> + ) + ) + } + }) + } +} +---- +<1> `classDirectories` needs to be read after evaluation phase in Gradle +<2> Currently, there is a bug in Gradle JaCoCo which requires the `excludes` to be specified in this manner - https://github.com/gradle/gradle/issues/14760. Once this issue is fixed, excludes +<3> Exclude all classes in `org/example/package` package +**** + == Conclusion You now have all the information you need to study the coverage of your tests! diff --git a/docs/src/main/asciidoc/writing-extensions.adoc b/docs/src/main/asciidoc/writing-extensions.adoc index 5ef15c1907b8b..98d1075b0a813 100644 --- a/docs/src/main/asciidoc/writing-extensions.adoc +++ b/docs/src/main/asciidoc/writing-extensions.adoc @@ -566,6 +566,9 @@ The plugin includes the `extensionDescriptor` task that will generate `META-INF/ The plugin also enables the `io.quarkus:quarkus-extension-processor` annotation processor in both `deployment` and `runtime` modules to collect and generate the rest of the xref:extension-metadata.adoc[Quarkus extension metadata]. The name of the deployment module can be configured in the plugin by setting the `deploymentModule` property. The property is set to `deployment` by default: +[role="primary asciidoc-tabs-sync-groovy"] +.Groovy DSL +**** [source,groovy,subs=attributes+] ---- plugins { @@ -578,9 +581,30 @@ quarkusExtension { } dependencies { - implementation platform('io.quarkus:quarkus-bom:{quarkus-version}') + implementation platform('{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}') } ---- +**** + +[role="secondary asciidoc-tabs-sync-kotlin"] +.Kotlin DSL +**** +[source,kotlin,subs=attributes+] +---- +plugins { + java + id("io.quarkus.extension") +} + +quarkusExtension { + deploymentModule = "deployment" +} + +dependencies { + implementation(platform("{quarkus-platform-groupid}:quarkus-bom:{quarkus-version}")) +} +---- +**** [[build-step-processors]]