Add a DSL option that enables the native-image agent (#263)

Author: lazar-mitrovic

docs/src/docs/asciidoc/gradle-plugin.adoc

@@ -156,6 +156,7 @@ If you do this, the plugin will search for 2 environment variables: `GRAALVM_HOM
 If one of them is set, it will assume that it points to a valid GraalVM installation and completely bypass toolchain selection.
 Therefore, it becomes your responsibility to make sure that the environment variable points to a JDK that is compatible with your build script requirements (in particular, the language version).
 
+[[configuration-options]]
 ==== Configuration options
 
 The following configuration options are available for building images:
@@ -349,18 +350,10 @@ The plugin will also substitute `{output_dir}` in the agent options to point to
 === Configuring agent options
 
 The native agent can be configured https://www.graalvm.org/reference-manual/native-image/Agent/[with additional options].
-This can be done using the `agent` configuration block:
+This can be done using the `agent` configuration block.
+Each agent option has a corresponding field in the DSL.
+See <<configuration-options>> for the full list of available options.
 
-.Configuring agent options
-[source, groovy, role="multi-language-sample"]
-----
-include::../snippets/gradle/groovy/build.gradle[tags=add-agent-options]
-----
-
-[source, kotlin, role="multi-language-sample"]
-----
-include::../snippets/gradle/kotlin/build.gradle.kts[tags=add-agent-options]
-----
 
 [[metadata-support]]
 == GraalVM Reachability Metadata Support

docs/src/docs/snippets/gradle/groovy/build.gradle

@@ -67,9 +67,9 @@ if (providers.environmentVariable("DISABLE_TOOLCHAIN").isPresent()) {
 
 // tag::all-config-options[]
 graalvmNative {
-    // Injects the native-image-agent into supported tasks if `-Pagent` is specified
     agent {
         defaultMode = "standard" // Default agent mode if one isn't specified using `-Pagent=mode_name`
+        enabled = true // Enables the agent
 
         modes {
             // The standard agent mode generates metadata without conditions.
@@ -78,7 +78,7 @@ graalvmNative {
             // The conditional agent mode generates metadata with conditions.
             conditional {
                 userCodeFilterPath = "path-to-filter.json" // Path to a filter file that determines classes which will be used in the metadata conditions.
-                extrFilterPath = "path-to-another-filter.json" // Optional, extra filter used to further filter the collected metadata.
+                extraFilterPath = "path-to-another-filter.json" // Optional, extra filter used to further filter the collected metadata.
             }
             // The direct agent mode allows users to directly pass options to the agent.
             direct {
@@ -165,33 +165,6 @@ graalvmNative {
 }
 // end::disable-test-support[]
 
-// tag::add-agent-options[]
-graalvmNative {
-    binaries.configureEach {
-        agent {
-            options.add("experimental-class-loader-support")
-        }
-    }
-}
-// end::add-agent-options[]
-
-// tag::add-agent-options-individual[]
-graalvmNative {
-    binaries {
-        main {
-            agent {
-                options.add("experimental-class-loader-support")
-            }
-        }
-        test {
-            agent {
-                options.add("access-filter-file=${projectDir}/src/test/resources/access-filter.json")
-            }
-        }
-    }
-}
-// end::add-agent-options-individual[]
-
 // tag::enable-metadata-repository[]
 graalvmNative {
     metadataRepository {

docs/src/docs/snippets/gradle/kotlin/build.gradle.kts

@@ -68,6 +68,49 @@ if (providers.environmentVariable("DISABLE_TOOLCHAIN").isPresent()) {
 
 // tag::all-config-options[]
 graalvmNative {
+    agent {
+        defaultMode.set("standard") // Default agent mode if one isn't specified using `-Pagent=mode_name`
+        enabled.set(true) // Enables the agent
+
+        modes {
+            // The standard agent mode generates metadata without conditions.
+            standard {
+            }
+            // The conditional agent mode generates metadata with conditions.
+            conditional {
+                userCodeFilterPath.set("path-to-filter.json") // Path to a filter file that determines classes which will be used in the metadata conditions.
+                extraFilterPath.set("path-to-another-filter.json") // Optional, extra filter used to further filter the collected metadata.
+            }
+            // The direct agent mode allows users to directly pass options to the agent.
+            direct {
+                // {output_dir} is a special string expanded by the plugin to where the agent files would usually be output.
+                options.add("config-output-dir={output_dir}")
+                options.add("experimental-configuration-with-origins")
+            }
+        }
+
+        callerFilterFiles.from("filter.json")
+        accessFilterFiles.from("filter.json")
+        builtinCallerFilter.set(true)
+        builtinHeuristicFilter.set(true)
+        enableExperimentalPredefinedClasses.set(false)
+        enableExperimentalUnsafeAllocationTracing.set(false)
+        trackReflectionMetadata.set(true)
+
+        // Copies metadata collected from tasks into the specified directories.
+        metadataCopy {
+            inputTaskNames.add("test") // Tasks previously executed with the agent attached.
+            outputDirectories.add("src/main/resources/META-INF/native-image")
+            mergeWithExisting.set(true) // Instead of copying, merge with existing metadata in the output directories.
+        }
+
+        /*
+        By default, if `-Pagent` is specified, all tasks that extend JavaForkOptions are instrumented.
+        This can be limited to only specific tasks that match this predicate.
+         */
+        tasksToInstrumentPredicate.set(t -> true)
+    }
+
     binaries {
         named("main") {
             // Main options
@@ -135,14 +178,6 @@ graalvmNative {
 }
 // end::custom-binary[]
 
-// tag::add-agent-options[]
-graalvmNative {
-    agent {
-        enableExperimentalPredefinedClasses = true
-    }
-}
-// end::add-agent-options[]
-
 // tag::enable-metadata-repository[]
 graalvmNative {
     metadataRepository {

native-gradle-plugin/src/main/java/org/graalvm/buildtools/gradle/NativeImagePlugin.java

@@ -523,7 +523,7 @@ private static Provider<String> agentProperty(Project project, AgentOptions opti
                     }
                     return options.getDefaultMode().get();
                 })
-                .orElse(project.provider(() -> "disabled"));
+                .orElse(options.getEnabled().map(enabled -> enabled ? options.getDefaultMode().get() : "disabled"));
     }
 
     private static void registerServiceProvider(Project project, Provider<NativeImageService> nativeImageServiceProvider) {

native-gradle-plugin/src/main/java/org/graalvm/buildtools/gradle/dsl/agent/AgentOptions.java

@@ -72,6 +72,13 @@ default void modes(Action<? super AgentModeOptions> spec) {
     @Optional
     Property<String> getDefaultMode();
 
+    /**
+     * Enables the agent.
+     */
+    @Input
+    @Optional
+    Property<Boolean> getEnabled();
+
     /**
      * Caller-filter files that will be passed to the agent.
      */

native-gradle-plugin/src/main/java/org/graalvm/buildtools/gradle/internal/DefaultGraalVmExtension.java

@@ -78,6 +78,7 @@ public DefaultGraalVmExtension(NamedDomainObjectContainer<NativeImageOptions> na
         AgentOptions agentOpts = getAgent();
         agentOpts.getTasksToInstrumentPredicate().convention(t -> true);
         agentOpts.getDefaultMode().convention("standard");
+        agentOpts.getEnabled().convention(false);
         agentOpts.getModes().getConditional().getParallel().convention(true);
         agentOpts.getMetadataCopy().getMergeWithExisting().convention(false);
         agentOpts.getFilterableEntries().convention(Arrays.asList("org.gradle.", "java.", "org.junit."));