Document test binary configuration (#509)

graalvm · Oct 10, 2023 · a007bf2 · a007bf2
1 parent 2efefc0
commit a007bf2
Show file tree

Hide file tree

Showing 3 changed files with 86 additions and 0 deletions.
diff --git a/docs/src/docs/asciidoc/gradle-plugin.adoc b/docs/src/docs/asciidoc/gradle-plugin.adoc
@@ -120,6 +120,17 @@ The main executable is configured by the image named `main`, while the test exec
 === Native image options
 
 The link:javadocs/native-gradle-plugin/org/graalvm/buildtools/gradle/dsl/NativeImageOptions.html[NativeImageOptions] allows you to tweak how the native image is going to be built.
+The plugin allows configuring the final binary, the <<test-binary-config,tests>> one, as well as apply options to both.
+
+[source,groovy,role="multi-language-sample"]
+----
+include::../snippets/gradle/groovy/build.gradle[tags=configure-binaries]
+----
+
+[source,kotlin,role="multi-language-sample"]
+----
+include::../snippets/gradle/kotlin/build.gradle.kts[tags=configure-binaries]
+----
 
 [[configuration-toolchains]]
 === Using Gradle toolchains
@@ -246,6 +257,22 @@ Currently, this feature requires the execution of the tests in the classic "JVM"
 ./gradlew nativeTest
 ----
 
+[[test-binary-config]]
+=== Configuring test image options
+
+You can fine-tune the test binary using the `test` binary configuration.
+The following example prints additional data for troubleshooting and sets the minimal optimizations.
+
+[source,groovy,role="multi-language-sample"]
+----
+include::../snippets/gradle/groovy/build.gradle[tags=configure-test-binary]
+----
+
+[source,kotlin,role="multi-language-sample"]
+----
+include::../snippets/gradle/kotlin/build.gradle.kts[tags=configure-test-binary]
+----
+
 [[testing-support-disabling]]
 === Disabling testing support
 

diff --git a/docs/src/docs/snippets/gradle/groovy/build.gradle b/docs/src/docs/snippets/gradle/groovy/build.gradle
@@ -214,3 +214,31 @@ tasks.named("jar") {
     from collectReachabilityMetadata
 }
 // end::include-metadata[]
+
+// tag::configure-binaries[]
+graalvmNative {
+    binaries {
+        main {
+            imageName = "my-app"
+            mainClass = "org.jackup.Runner"
+            buildArgs.add("-O4")
+        }
+        test {
+            buildArgs.add("-O0")
+        }
+    }
+    binaries.all {
+        buildArgs.add("--verbose")
+    }
+}
+// end::configure-binaries[]
+
+// tag::configure-test-binary[]
+graalvmNative {
+    binaries {
+        test {
+            buildArgs.addAll('--verbose', '-O0')
+        }
+    }
+}
+// end::configure-test-binary[]
diff --git a/docs/src/docs/snippets/gradle/kotlin/build.gradle.kts b/docs/src/docs/snippets/gradle/kotlin/build.gradle.kts
@@ -228,3 +228,34 @@ tasks.named("jar", Jar) {
 	from(collectReachabilityMetadata)
 }
 // end::include-metadata[]
+
+// tag::configure-binaries[]
+graalvmNative {
+    binaries {
+        named("main") {
+            imageName.set("my-app")
+            mainClass.set("org.jackup.Runner")
+            buildArgs.add("-O4")
+        }
+        named("test") {
+            buildArgs.add("-O0")
+        }
+    }
+    binaries.all {
+        buildArgs.add("--verbose")
+    }
+}
+// end::configure-binaries[]
+
+// tag::configure-test-binary[]
+graalvmNative {
+    binaries {
+        named("main") {
+            mainClass.set("org.test.Main")
+        }
+        named("test") {
+            buildArgs.addAll("--verbose", "-O0")
+        }
+    }
+}
+// end::configure-test-binary[]