Add plugin descriptions

native-gradle-plugin/src/functionalTest/groovy/org/graalvm/buildtools/gradle/OfficialMetadataRepoFunctionalTest.groovy

@@ -59,10 +59,12 @@ class OfficialMetadataRepoFunctionalTest extends AbstractFunctionalTest {
             succeeded ':jar', ':nativeCompile', ':nativeRun'
         }
 
+        and: "the run succeeded and retrieved data from the database"
+        outputContains "Customers in the database"
+
         and: "finds metadata in the remote repository"
         outputContains "[graalvm reachability metadata repository for com.h2database:h2:"
         outputContains "Configuration directory is com.h2database" + File.separator + "h2" + File.separator
-        outputDoesNotContain "Falling back to the default repository at"
     }
 
     def "the application doesn't run when usage of the official metadata repository is disabled"() {

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

@@ -279,6 +279,8 @@ private void configureJavaProject(Project project, Provider<NativeImageService>
 
         TaskProvider<BuildNativeImageTask> imageBuilder = tasks.named(NATIVE_COMPILE_TASK_NAME, BuildNativeImageTask.class);
         tasks.register(DEPRECATED_NATIVE_BUILD_TASK, t -> {
+            t.setGroup(LifecycleBasePlugin.BUILD_GROUP);
+            t.setDescription("Deprecated alias for nativeCompile.");
             t.dependsOn(imageBuilder);
             t.doFirst("Warn about deprecation", task -> task.getLogger().warn("Task " + DEPRECATED_NATIVE_BUILD_TASK + " is deprecated. Use " + NATIVE_COMPILE_TASK_NAME + " instead."));
         });
@@ -290,7 +292,7 @@ private void configureJavaProject(Project project, Provider<NativeImageService>
 
         project.getTasks().register("metadataCopy", MetadataCopyTask.class, task -> {
             task.setGroup(LifecycleBasePlugin.BUILD_GROUP);
-            task.setDescription("Copies metadata collected from tasks instrumented with the agent into target directories");
+            task.setDescription("Copies and optionally merges metadata collected by agent-instrumented tasks into target directories.");
             task.getInputTaskNames().set(graalExtension.getAgent().getMetadataCopy().getInputTaskNames());
             task.getOutputDirectories().set(graalExtension.getAgent().getMetadataCopy().getOutputDirectories());
             task.getMergeWithExisting().set(graalExtension.getAgent().getMetadataCopy().getMergeWithExisting());
@@ -299,7 +301,7 @@ private void configureJavaProject(Project project, Provider<NativeImageService>
 
         project.getTasks().register("collectReachabilityMetadata", CollectReachabilityMetadata.class, task -> {
             task.setGroup(LifecycleBasePlugin.BUILD_GROUP);
-            task.setDescription("Obtains native reachability metadata for the runtime classpath configuration");
+            task.setDescription("Collects reachability metadata for the runtime classpath.");
             task.setClasspath(project.getConfigurations().getByName(JavaPlugin.RUNTIME_CLASSPATH_CONFIGURATION_NAME));
         });
 
@@ -331,7 +333,7 @@ private void configureAutomaticTaskCreation(Project project,
             }
             TaskProvider<BuildNativeImageTask> imageBuilder = tasks.register(compileTaskName,
                 BuildNativeImageTask.class, builder -> {
-                    builder.setDescription("Compiles a native image for the " + options.getName() + " binary");
+                    builder.setDescription("Builds a native executable for the " + options.getName() + " binary.");
                     builder.setGroup(LifecycleBasePlugin.BUILD_GROUP);
                     builder.getOptions().convention(options);
                     builder.getUseArgFile().convention(graalExtension.getUseArgFile());
@@ -345,7 +347,7 @@ private void configureAutomaticTaskCreation(Project project,
             }
             tasks.register(runTaskName, NativeRunTask.class, task -> {
                 task.setGroup(LifecycleBasePlugin.BUILD_GROUP);
-                task.setDescription("Executes the " + options.getName() + " native binary");
+                task.setDescription("Runs the " + options.getName() + " native binary.");
                 task.getImage().convention(imageBuilder.flatMap(BuildNativeImageTask::getOutputFile));
                 task.getRuntimeArgs().convention(options.getRuntimeArgs());
                 var useLayers = options.getLayers()
@@ -579,7 +581,7 @@ private static GraalVMReachabilityMetadataRepositoryExtension reachabilityExtens
     private void configureClasspathJarFor(TaskContainer tasks, NativeImageOptions options, TaskProvider<BuildNativeImageTask> imageBuilder) {
         String baseName = imageBuilder.getName();
         TaskProvider<Jar> classpathJar = tasks.register(baseName + "ClasspathJar", Jar.class, jar -> {
-            jar.setDescription("Builds a pathing jar for the " + options.getName() + " native binary");
+            jar.setDescription("Builds a pathing JAR for the " + options.getName() + " native binary classpath.");
             jar.from(
                 options.getClasspath()
                     .getElements()
@@ -648,7 +650,7 @@ private TaskProvider<GenerateResourcesConfigFile> registerResourcesConfigTask(Pr
                                                                                   FileCollection transitiveProjectArtifacts,
                                                                                   String name) {
         return tasks.register(name, GenerateResourcesConfigFile.class, task -> {
-            task.setDescription("Generates a GraalVM resource-config.json file");
+            task.setDescription("Scans resources and generates a resource-config.json file for the " + options.getName() + " binary.");
             task.getOptions().convention(options.getResources());
             task.getClasspath().from(options.getClasspath());
             task.getTransitiveProjectArtifacts().from(transitiveProjectArtifacts);
@@ -702,6 +704,8 @@ public void registerTestBinary(Project project,
         });
         if (isPrimaryTest) {
             tasks.register(DEPRECATED_NATIVE_TEST_BUILD_TASK, t -> {
+                t.setGroup(LifecycleBasePlugin.VERIFICATION_GROUP);
+                t.setDescription("Deprecated alias for nativeTestCompile.");
                 t.dependsOn(testImageBuilder);
                 t.doFirst("Warn about deprecation", task -> task.getLogger().warn("Task " + DEPRECATED_NATIVE_TEST_BUILD_TASK + " is deprecated. Use " + NATIVE_TEST_COMPILE_TASK_NAME + " instead."));
             });

native-gradle-plugin/src/test/groovy/org/graalvm/buildtools/gradle/NativeImagePluginTest.groovy

@@ -3,6 +3,7 @@ package org.graalvm.buildtools.gradle
 import org.graalvm.buildtools.gradle.dsl.GraalVMExtension
 import org.graalvm.buildtools.gradle.dsl.GraalVMReachabilityMetadataRepositoryExtension
 import org.gradle.api.Project
+import org.gradle.api.Task
 import org.gradle.testfixtures.ProjectBuilder
 import spock.lang.Issue
 import spock.lang.Specification
@@ -49,6 +50,30 @@ class NativeImagePluginTest extends Specification {
         "https://custom.uri"                 | 'ignored'             | 'https://custom.uri'                                                                                                  | null
     }
 
+    def "registers descriptions for user-facing tasks"() {
+        when:
+        project.plugins.apply("java")
+
+        then:
+        taskDescription("nativeCompile") == "Builds a native executable for the main binary."
+        taskDescription("nativeRun") == "Runs the main native binary."
+        taskDescription("nativeBuild") == "Deprecated alias for nativeCompile."
+        taskDescription("metadataCopy") == "Copies and optionally merges metadata collected by agent-instrumented tasks into target directories."
+        taskDescription("collectReachabilityMetadata") == "Collects reachability metadata for the runtime classpath."
+        taskDescription("nativeCompileClasspathJar") == "Builds a pathing JAR for the main native binary classpath."
+        taskDescription("generateResourcesConfigFile") == "Scans resources and generates a resource-config.json file for the main binary."
+        taskDescription("nativeTestCompile") == "Builds a native executable for the test binary."
+        taskDescription("nativeTest") == "Runs the test native binary."
+        taskDescription("nativeTestBuild") == "Deprecated alias for nativeTestCompile."
+        taskDescription("generateTestResourcesConfigFile") == "Scans resources and generates a resource-config.json file for the test binary."
+    }
+
+    private String taskDescription(String name) {
+        Task task = project.tasks.getByName(name)
+        assert task.description != null
+        task.description
+    }
+
     private void repositoryUriFor(String configuredUri, String version) {
         if (configuredUri != null) {
             reachabilityMetadataRepositoryExtension.uri.set(new URI(configuredUri))

native-maven-plugin/build-plugins/src/main/kotlin/org.graalvm.build.maven-plugin.gradle.kts

@@ -59,6 +59,9 @@ val preparePluginDescriptor = tasks.register<Copy>("preparePluginDescriptor") {
     }) {
         rename { "pom.xml" }
     }
+    from(sourceSets.getByName("main").allJava) {
+        into("src/main/java")
+    }
     from(sourceSets.getByName("main").output.classesDirs) {
         into("target/classes")
     }

native-maven-plugin/build.gradle.kts

@@ -40,7 +40,6 @@
  */
 
 import org.graalvm.build.maven.MavenTask
-import org.gradle.util.GFileUtils
 
 plugins {
     `java-library`
@@ -154,7 +153,13 @@ val prepareMavenLocalRepo = tasks.register<MavenTask>("prepareMavenLocalRepo") {
 }
 
 val launcher = javaToolchains.launcherFor {
-    languageVersion.set(JavaLanguageVersion.of(17))
+    languageVersion.set(
+        providers.gradleProperty("mavenFunctionalTestJavaVersion")
+            .orElse(providers.gradleProperty("javaToolchainVersion"))
+            .orElse("17")
+            .map(String::toInt)
+            .map(JavaLanguageVersion::of)
+    )
 }
 
 tasks {

native-maven-plugin/src/functionalTest/groovy/org/graalvm/buildtools/maven/JavaApplicationFunctionalTest.groovy

@@ -143,4 +143,32 @@ class JavaApplicationFunctionalTest extends AbstractGraalVMMavenFunctionalTest {
         outputContains "Args file written to: target" + File.separator + "native-image"
     }
 
+    def "help describe includes goal descriptions"() {
+        withSample("java-application")
+
+        when:
+        mvn 'help:describe', "-Dplugin=org.graalvm.buildtools:native-maven-plugin:${System.getProperty('native.maven.plugin.version')}"
+
+        then:
+        buildSucceeded
+        outputContains "org.graalvm.buildtools:native-maven-plugin:${System.getProperty('native.maven.plugin.version')}"
+        outputContains "native:add-reachability-metadata"
+        outputContains "metadata repository to the project's output directory."
+        outputContains "native:compile"
+        outputContains "Builds a native executable by forking Maven"
+        outputContains "native:compile-no-fork"
+        outputContains "without forking a separate Maven build."
+        outputContains "native:generateResourceConfig"
+        outputContains "generates resource metadata for them."
+        outputContains "native:generateTestResourceConfig"
+        outputContains "native:merge-agent-files"
+        outputContains "Merges tracing agent output"
+        outputContains "native:metadata-copy"
+        outputContains "META-INF/native-image"
+        outputContains "native:test"
+        outputContains "Builds and runs the project's tests as native executables."
+        outputContains "native:write-args-file"
+        outputContains "an args file that can be reused outside Maven."
+    }
+
 }

native-maven-plugin/src/functionalTest/groovy/org/graalvm/buildtools/maven/OfficialMetadataRepositoryFunctionalTest.groovy

@@ -62,7 +62,6 @@ class OfficialMetadataRepositoryFunctionalTest extends AbstractGraalVMMavenFunct
         and: "finds metadata in the remote repository"
         outputContains "[graalvm reachability metadata repository for com.h2database:h2:"
         outputContains "Configuration directory is com.h2database" + File.separator + "h2" + File.separator
-        outputDoesNotContain "Falling back to the default repository."
     }
 
     @IgnoreIf({ os.windows })

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/AddReachabilityMetadataMojo.java

@@ -57,6 +57,9 @@
 import org.apache.maven.plugins.annotations.ResolutionScope;
 import org.graalvm.reachability.DirectoryConfiguration;
 
+/**
+ * Adds dependency reachability metadata from the configured metadata repository to the project's output directory.
+ */
 @Mojo(name = "add-reachability-metadata", defaultPhase = LifecyclePhase.GENERATE_RESOURCES, requiresDependencyResolution = ResolutionScope.RUNTIME, requiresDependencyCollection = ResolutionScope.RUNTIME)
 public class AddReachabilityMetadataMojo extends AbstractNativeMojo {
 

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/DeprecatedNativeBuildMojo.java

@@ -47,8 +47,7 @@
 import org.apache.maven.plugins.annotations.ResolutionScope;
 
 /**
- * Mojo used to invoke native image building by attaching it to a phase.
- * Deprecated in favor of compile-no-fork goal.
+ * Deprecated alias for the {@code native:compile-no-fork} goal for lifecycle-bound native image builds.
  */
 @Deprecated
 @Mojo(name = "build", defaultPhase = LifecyclePhase.PACKAGE,

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/MergeAgentFilesMojo.java

@@ -59,6 +59,9 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+/**
+ * Merges tracing agent output from one or more sessions into a single metadata directory.
+ */
 @Mojo(name = "merge-agent-files", defaultPhase = LifecyclePhase.TEST)
 public class MergeAgentFilesMojo extends AbstractMergeAgentFilesMojo {
     @Parameter(defaultValue = "${project}", readonly = true, required = true)

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/MetadataCopyMojo.java

@@ -62,6 +62,9 @@
 import java.util.Objects;
 import java.util.stream.Collectors;
 
+/**
+ * Copies and optionally merges tracing agent metadata into {@code META-INF/native-image} for packaging.
+ */
 @Mojo(name = "metadata-copy", defaultPhase = LifecyclePhase.NONE)
 public class MetadataCopyMojo extends AbstractMergeAgentFilesMojo {
 

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/NativeBuildResourceConfigMojo.java

@@ -45,6 +45,9 @@
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.ResolutionScope;
 
+/**
+ * Scans main resources and generates resource metadata for them.
+ */
 @Mojo(
         name = "generateResourceConfig",
         defaultPhase = LifecyclePhase.PACKAGE,

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/NativeBuildTestResourceConfigMojo.java

@@ -50,6 +50,9 @@
 import java.util.Collection;
 import java.util.stream.Collectors;
 
+/**
+ * Scans test resources and generates resource metadata for them.
+ */
 @Mojo(
         name = "generateTestResourceConfig",
         defaultPhase = LifecyclePhase.PACKAGE,

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/NativeCompileMojo.java

@@ -48,8 +48,9 @@
 
 
 /**
- * This goal builds native images.
- * It should be invoked from the command line as a single goal (`mvn native:compile`).
+ * Builds a native executable by forking Maven to the {@code package} phase before invoking {@code native-image}.
+ *
+ * It should be invoked from the command line as a single goal ({@code mvn native:compile}).
  */
 @Mojo(name = "compile", defaultPhase = LifecyclePhase.PACKAGE,
         requiresDependencyResolution = ResolutionScope.RUNTIME,

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/NativeCompileNoForkMojo.java

@@ -61,8 +61,7 @@
 import java.util.function.BiFunction;
 
 /**
- * This goal runs native builds. It functions the same as the native:compile goal, but it
- * does not fork the build, so it is suitable for attaching to the build lifecycle.
+ * Builds a native executable in the current Maven lifecycle without forking a separate Maven build.
  */
 @Mojo(name = "compile-no-fork", defaultPhase = LifecyclePhase.PACKAGE,
         requiresDependencyResolution = ResolutionScope.RUNTIME,

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/NativeTestMojo.java

@@ -84,7 +84,7 @@
 import static org.graalvm.buildtools.utils.NativeImageConfigurationUtils.NATIVE_TESTS_EXE;
 
 /**
- * This goal builds and runs native tests.
+ * Builds and runs the project's tests as native executables.
  *
  * @author Sebastien Deleuze
  */

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/WriteArgsFileMojo.java

@@ -54,8 +54,7 @@
 import java.util.stream.Stream;
 
 /**
- * Persists the arguments file to be used by the native-image command. This can be useful in situations where
- * Native Build Tools plugin is not available, for example, when running native-image in a Docker container.
+ * Writes the {@code native-image} arguments for this project to an args file that can be reused outside Maven.
  *
  * The path to the args file is stored in the project properties under the key {@code graalvm.native-image.args-file}.
  *

samples/metadata-repo-integration/pom.xml

@@ -110,6 +110,11 @@
                                 <phase>package</phase>
                             </execution>
                         </executions>
+                        <configuration>
+                            <buildArgs>
+                                <buildArg>--initialize-at-build-time=ch.qos.logback.classic.Logger</buildArg>
+                            </buildArgs>
+                        </configuration>
                     </plugin>
                 </plugins>
             </build>
@@ -133,6 +138,9 @@
                             </execution>
                         </executions>
                         <configuration>
+                            <buildArgs>
+                                <buildArg>--initialize-at-build-time=ch.qos.logback.classic.Logger</buildArg>
+                            </buildArgs>
                             <!-- tag::metadata-versioned[] -->
                             <metadataRepository>
                                 <enabled>true</enabled>
@@ -163,6 +171,9 @@
                             </execution>
                         </executions>
                         <configuration>
+                            <buildArgs>
+                                <buildArg>--initialize-at-build-time=ch.qos.logback.classic.Logger</buildArg>
+                            </buildArgs>
                             <!-- tag::metadata-disable[] -->
                             <metadataRepository>
                                 <enabled>false</enabled>
@@ -192,6 +203,9 @@
                             </execution>
                         </executions>
                         <configuration>
+                            <buildArgs>
+                                <buildArg>--initialize-at-build-time=ch.qos.logback.classic.Logger</buildArg>
+                            </buildArgs>
                             <metadataRepository>
                                 <version>0.3.20</version>
                             </metadataRepository>