Agent doc refactor and support for additional options

Author: Aleksandar Gradinac

common/utils/src/main/java/org/graalvm/buildtools/agent/AgentConfiguration.java

@@ -49,18 +49,41 @@ public class AgentConfiguration implements Serializable {
 
     private final Collection<String> callerFilterFiles;
     private final Collection<String> accessFilterFiles;
+    private final boolean builtinCallerFilter;
+    private final boolean builtinHeuristicFilter;
+    private final boolean experimentalPredefinedClasses;
+    private final boolean experimentalUnsafeAllocationTracing;
+    private final boolean trackReflectionMetadata;
+
     private final AgentMode agentMode;
 
-    public AgentConfiguration(Collection<String> callerFilterFiles, Collection<String> accessFilterFiles, AgentMode agentMode) {
+    public AgentConfiguration(Collection<String> callerFilterFiles,
+                              Collection<String> accessFilterFiles,
+                              boolean builtinCallerFilter,
+                              boolean builtinHeuristicFilter,
+                              boolean experimentalPredefinedClasses,
+                              boolean experimentalUnsafeAllocationTracing,
+                              boolean trackReflectionMetadata,
+                              AgentMode agentMode) {
         this.callerFilterFiles = callerFilterFiles;
         this.accessFilterFiles = accessFilterFiles;
+        this.builtinCallerFilter = builtinCallerFilter;
+        this.builtinHeuristicFilter = builtinHeuristicFilter;
+        this.experimentalPredefinedClasses = experimentalPredefinedClasses;
+        this.experimentalUnsafeAllocationTracing = experimentalUnsafeAllocationTracing;
+        this.trackReflectionMetadata = trackReflectionMetadata;
         this.agentMode = agentMode;
     }
 
     public List<String> getAgentCommandLine() {
         List<String> cmdLine = new ArrayList<>(agentMode.getAgentCommandLine());
         appendOptionToValues("caller-filter-file=", callerFilterFiles, cmdLine);
         appendOptionToValues("access-filter-file=", accessFilterFiles, cmdLine);
+        cmdLine.add("builtin-caller-filter=" + builtinCallerFilter);
+        cmdLine.add("builtin-heuristic-filter=" + builtinHeuristicFilter);
+        cmdLine.add("experimental-class-define-support=" + experimentalPredefinedClasses);
+        cmdLine.add("experimental-unsafe-allocation-support=" + experimentalUnsafeAllocationTracing);
+        cmdLine.add("track-reflection-metadata=" + trackReflectionMetadata);
         return cmdLine;
     }
 

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

@@ -285,32 +285,41 @@ The same mechanism can be used if you have multiple test tasks for a single test
 
 If your project requires reflection, classpath resources, dynamic proxies or other features requiring explicit native configuration, it may prove helpful to first run your application or tests using the https://www.graalvm.org/reference-manual/native-image/Agent/[`native-image-agent`].
 
-The Native Image Gradle plugin simplifies generation of the required configuration files by injecting the agent automatically for you (this includes, but is not limited to the reflection file).
+The Native Image Gradle plugin simplifies generation of the required metadata files by injecting the agent automatically for you (this includes, but is not limited to the reflection file).
 
-This should be as easy as appending `-Pagent` to the `run` and `nativeBuild`, or `test` and `nativeTest` task invocations:
+Any task that extends `JavaForkOptions` (like `test`, `run` etc) can be instrumented by passing `-Pagent` to gradle when running said tasks.
+
+The agent can run in multiple modes that dictate how the metadata is collected and merged.
+
+Once the metadata is collected, it can be copied into the project using the `metadataCopy` task.
 
 [source,bash]
 ----
 ./gradlew -Pagent run # Runs on JVM with native-image-agent.
-./gradlew -Pagent nativeCompile # Builds image using configuration acquired by agent.
+./gradlew metadataCopy --task run --dir src/main/resources/META-INF/native-image # Copies the metadata collected by the agent into the project sources
+./gradlew nativeCompile # Builds image using metadata acquired by the agent.
 
 # For testing
-./gradlew -Pagent test # Runs on JVM with native-image-agent.
-./gradlew -Pagent nativeTest # Builds image using configuration acquired by agent.
+./gradlew -Pagent nativeTest # Runs on JVM with the native-image agent, collects the metadata and uses it for testing on native-image.
 ----
 
-The agent can also be enabled by setting the corresponding DSL flag; however, that is not recommended since this is a development mode feature only.
+The agent can run in multiple modes:
+* Standard - Collects metadata without conditions. This is recommended if you are building an executable.
+* Conditional - Collects metadata with conditions. This is recommended if you are creating conditional metadata for a library intended for further use.
+* Direct - For advanced users only. This mode allows directly controlling the command line passed to the agent.
+
+The default mode is specified in the DSL but can be changed by passing the mode name to Gradle when using the agent: `-Pagent=conditional`
 
 The generated configuration files will be found in the `${buildDir}/native/agent-output/${taskName}` directory, for example, `build/native/agent-output/run`.
-Although those files will be automatically used if you run your build with the agent enabled, you should consider reviewing them and adding them to your sources instead.
+The plugin will also substitute `{output_dir}` in the agent options to point to this directory during the agent run.
 
 [[agent-support-configuring-options]]
 === 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:
 
-.Configuring agent options for every binary
+.Configuring agent options
 [source, groovy, role="multi-language-sample"]
 ----
 include::../snippets/gradle/groovy/build.gradle[tags=add-agent-options]
@@ -321,20 +330,6 @@ include::../snippets/gradle/groovy/build.gradle[tags=add-agent-options]
 include::../snippets/gradle/kotlin/build.gradle.kts[tags=add-agent-options]
 ----
 
-You may also define distinct agent options for different images.
-In the following example, the agent used for instrumentation for the main image has distinct options from the test ones:
-
-.Configuring agent options specifically
-[source, groovy, role="multi-language-sample"]
-----
-include::../snippets/gradle/groovy/build.gradle[tags=add-agent-options-individual]
-----
-
-[source, kotlin, role="multi-language-sample"]
-----
-include::../snippets/gradle/kotlin/build.gradle.kts[tags=add-agent-options-individual]
-----
-
 [[metadata-support]]
 == JVM Reachability Metadata support
 

docs/src/docs/asciidoc/index.adoc

@@ -14,6 +14,16 @@ If you are interested in contributing, please refer to our https://github.com/gr
 
 [[changelog]]
 == Changelog
+=== Release 0.9.12
+
+==== Gradle plugin
+* Completely reworked agent support - **BREAKING CHANGE**
+* The agent block is no longer tied to the target binary.
+* The agent can now instrument any task that extends `JavaForkOptions`.
+* Introduced the `metadataCopy` task.
+* Introduced the concept of agent modes.
+** Under the hood, the agent mode dictates what options are passed to the agent and how metadata produced by multiple runs get merged.
+
 === Release 0.9.11
 
 ==== Maven plugin

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

@@ -67,6 +67,49 @@ 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`
+
+        modes {
+            // The standard agent mode generates metadata without conditions.
+            standard {
+            }
+            // 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.
+            }
+            // 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 = true
+        builtinHeuristicFilter = true
+        enableExperimentalPredefinedClasses = false
+        enableExperimentalUnsafeAllocationTracing = false
+        trackReflectionMetadata = 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 = 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 = t -> true
+    }
+
     binaries {
         main {
             // Main options
@@ -87,11 +130,6 @@ graalvmNative {
             // Runtime options
             runtimeArgs.add('--help') // Passes '--help' to built image, during "nativeRun" task
 
-            // Development options
-            agent {
-                enabled = true // Enables the reflection agent. Can be also set on command line using '-Pagent'
-            }
-
             useFatJar = true // Instead of passing each jar individually, builds a fat jar
         }
     }

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

@@ -88,11 +88,6 @@ graalvmNative {
             // Runtime options
             runtimeArgs.add("--help") // Passes '--help' to built image, during "nativeRun" task
 
-            // Development options
-            agent {
-                enabled.set(true) // Enables the reflection agent. Can be also set on command line using '-Pagent'
-            }
-
             useFatJar.set(true) // Instead of passing each jar individually, builds a fat jar
         }
     }
@@ -138,31 +133,12 @@ graalvmNative {
 
 // tag::add-agent-options[]
 graalvmNative {
-    binaries.configureEach {
-        agent {
-            options.add("experimental-class-loader-support")
-        }
+    agent {
+        enableExperimentalPredefinedClasses = true
     }
 }
 // end::add-agent-options[]
 
-// tag::add-agent-options-individual[]
-graalvmNative {
-    binaries {
-        named("main") {
-            agent {
-                options.add("experimental-class-loader-support")
-            }
-        }
-        named("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 {

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

@@ -54,33 +54,85 @@
 
 @SuppressWarnings({"unused"})
 public interface AgentOptions {
+    /**
+     * Contains configuration of supported agent modes.
+     */
     @Nested
     AgentModeOptions getModes();
 
     default void modes(Action<? super AgentModeOptions> spec) {
         spec.execute(getModes());
     }
 
+    /**
+     * The default agent mode name when the agent is in use.
+     */
     @Input
     @Optional
     Property<String> getDefaultMode();
 
+    /**
+     * Caller-filter files that will be passed to the agent.
+     */
     @InputFiles
     @Optional
     ConfigurableFileCollection getCallerFilterFiles();
 
+    /**
+     * Access-filter files that will be passed to the agent.
+     */
     @InputFiles
     @Optional
     ConfigurableFileCollection getAccessFilterFiles();
 
+    /**
+     * Toggles the builtin agent caller filter.
+     */
+    @Optional
+    Property<Boolean> getBuiltinCallerFilter();
+
+    /**
+     * Toggles the builtin agent heuristic filter.
+     */
+    @Optional
+    Property<Boolean> getBuiltinHeuristicFilter();
+
+
+    /**
+     * Toggles the experimental support for predefined classes.
+     */
+    @Optional
+    Property<Boolean> getEnableExperimentalPredefinedClasses();
+
+
+    /**
+     * Toggles the experimental support for unsafe allocation tracing.
+     */
+    @Optional
+    Property<Boolean> getEnableExperimentalUnsafeAllocationTracing();
+
+
+    /**
+     * Toggles the distinction between queried and used metadata.
+     */
+    @Optional
+    Property<Boolean> getTrackReflectionMetadata();
+
+    /**
+     * Configuration of the metadata copy task.
+     */
     @Nested
     MetadataCopyOptions getMetadataCopy();
 
     default void metadataCopy(Action<? super MetadataCopyOptions> spec) {
         spec.execute(getMetadataCopy());
     }
 
+    /**
+     * Specifies prefixes that will be used to further filter files produced by the agent.
+     */
     @Input
+    @Optional
     ListProperty<String> getFilterableEntries();
 
     /**

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

@@ -75,11 +75,17 @@ public DefaultGraalVmExtension(NamedDomainObjectContainer<NativeImageOptions> na
         getToolchainDetection().convention(true);
         nativeImages.configureEach(options -> options.getJavaLauncher().convention(defaultJavaLauncher));
         getTestSupport().convention(true);
-        getAgent().getTasksToInstrumentPredicate().convention(t -> true);
-        getAgent().getDefaultMode().convention("standard");
-        getAgent().getModes().getConditional().getParallel().convention(true);
-        getAgent().getMetadataCopy().getMergeWithExisting().convention(false);
-        getAgent().getFilterableEntries().convention(Arrays.asList("org.gradle.", "java.", "org.junit."));
+        AgentOptions agentOpts = getAgent();
+        agentOpts.getTasksToInstrumentPredicate().convention(t -> true);
+        agentOpts.getDefaultMode().convention("standard");
+        agentOpts.getModes().getConditional().getParallel().convention(true);
+        agentOpts.getMetadataCopy().getMergeWithExisting().convention(false);
+        agentOpts.getFilterableEntries().convention(Arrays.asList("org.gradle.", "java.", "org.junit."));
+        agentOpts.getBuiltinHeuristicFilter().convention(true);
+        agentOpts.getBuiltinCallerFilter().convention(true);
+        agentOpts.getEnableExperimentalPredefinedClasses().convention(false);
+        agentOpts.getEnableExperimentalUnsafeAllocationTracing().convention(true);
+        agentOpts.getTrackReflectionMetadata().convention(true);
         configureToolchain();
     }
 

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

@@ -87,7 +87,14 @@ public static Provider<AgentConfiguration> getAgentConfiguration(Provider<String
                 default:
                     throw new GradleException("Unknown agent mode selected: " + name);
             }
-            return new AgentConfiguration(getFilePaths(callerFilterFiles), getFilePaths(accessFilterFiles), agentMode);
+            return new AgentConfiguration(getFilePaths(callerFilterFiles),
+                    getFilePaths(accessFilterFiles),
+                    options.getBuiltinCallerFilter().get(),
+                    options.getBuiltinHeuristicFilter().get(),
+                    options.getEnableExperimentalPredefinedClasses().get(),
+                    options.getEnableExperimentalUnsafeAllocationTracing().get(),
+                    options.getTrackReflectionMetadata().get(),
+                    agentMode);
         });
     }