Respect build-tool console colors for Native Image output (#961)

* Respect Gradle plain console for Native Image output

* Respect Maven console colors for Native Image

* Ground Gradle console color unit tests

* Place test citations before issue annotations

Author: jormundur00

common/utils/src/main/java/org/graalvm/buildtools/model/resources/NativeImageFlags.java

@@ -42,6 +42,8 @@
 
 public abstract class NativeImageFlags {
     public static final String BUILD_OUTPUT_COLORFUL = "-H:+BuildOutputColorful";
+    // Legacy console-color arguments are shared by both adapters. §root/FS-native-builds.2.
+    public static final String BUILD_OUTPUT_COLORLESS = "-H:-BuildOutputColorful";
     public static final String COLOR = "--color";
     public static final String CONFIGURATION_FILE_DIRECTORIES = "-H:ConfigurationFileDirectories";
     public static final String LAYER_CREATE = "-H:LayerCreate";

docs/spec/functional/native-image-builds.md

@@ -33,6 +33,11 @@ Both plugins must construct the `native-image` command line through shared utili
 [§common/FS-common-libraries.1](../../../common/docs/functional-spec.md#1-shared-native-image-utilities) so escaping, quoting, and argument-file conversion stay identical.
 Plugin-specific string handling must not bypass those utilities.
 
+When a build tool disables colored console output, its adapter must explicitly disable Native
+Image colors with the flag supported by the discovered Native Image version. When console colors
+are enabled, plugin-specific rich-output configuration may enable them explicitly. User-supplied
+build arguments retain precedence over the adapter's detected console mode.
+
 When a user-configured option set exceeds platform argument limits, or when configuration requests
 it explicitly, the command line must be written as a Native Image argument file (`@<path>`).
 

native-gradle-plugin/docs/functional/native-image-invocation.md

@@ -26,6 +26,10 @@ configuration directories, generated resources, reachability metadata, layer opt
 conversion must come from common utilities rather than Gradle-only string handling, keeping Gradle
 aligned with [§root/FS-option-precedence](../../../docs/spec/functional/option-precedence.md#fs-option-precedence-command-line-input-and-durable-configuration-produce-one-option-state).
 
+When Gradle uses its plain console, the Native Image invocation must explicitly disable colorful
+build output. Otherwise, the `richOutput` option controls Native Image's color-enabled argument,
+adapting [§root/FS-native-builds.2](../../../docs/spec/functional/native-image-builds.md#2-command-line-construction).
+
 For a layer created from declared JARs, the command line must use those JARs as its classpath so
 the layer input remains limited to the declaration. A layer created from packages must instead
 retain the binary classpath, which supplies the classes selected by those package names.

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

@@ -43,10 +43,13 @@ package org.graalvm.buildtools.gradle
 
 import org.gradle.util.GradleVersion
 import org.graalvm.buildtools.gradle.fixtures.AbstractFunctionalTest
+import org.graalvm.buildtools.gradle.fixtures.GraalVMSupport
+import org.graalvm.buildtools.utils.NativeImageUtils
 import spock.lang.Ignore
 import spock.lang.IgnoreIf
 import spock.lang.Issue
 import spock.lang.Requires
+import spock.lang.Unroll
 
 import java.nio.file.Files
 
@@ -180,6 +183,36 @@ class JavaApplicationFunctionalTest extends AbstractFunctionalTest {
 
     }
 
+    // Gradle console mode controls Native Image color arguments. §FS-native-invocation.3.
+    @Issue("https://github.com/graalvm/native-build-tools/issues/366")
+    @Unroll
+    def "passes Gradle's #console console color mode to Native Image"() {
+        given:
+        withSample("java-application")
+        buildFile << """
+            graalvmNative {
+                binaries.all {
+                    richOutput = true
+                    verbose = true
+                }
+            }
+        """.stripIndent()
+
+        when:
+        run 'nativeCompile', "--console=${console}"
+
+        then:
+        tasks {
+            succeeded ':nativeCompile'
+        }
+        outputContains expectedColorArgument
+
+        where:
+        console | expectedColorArgument
+        'plain' | (NativeImageUtils.getMajorJDKVersion(GraalVMSupport.getGraalVMHomeVersionString()) >= 21 ? '--color=never' : '-H:-BuildOutputColorful')
+        'rich'  | (NativeImageUtils.getMajorJDKVersion(GraalVMSupport.getGraalVMHomeVersionString()) >= 21 ? '--color=always' : '-H:+BuildOutputColorful')
+    }
+
     @Issue("https://github.com/graalvm/native-build-tools/issues/129")
     def "can build a native image with dependencies only needed by native image"() {
         def nativeApp = getExecutableFile("build/native/nativeCompile/java-application")

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

@@ -84,7 +84,7 @@ public class NativeImageCommandLineProvider implements CommandLineArgumentProvid
     private final Provider<RegularFile> classpathJar;
     private final Provider<Boolean> useArgFile;
     private final Provider<Integer> majorJDKVersion;
-    private final Provider<Boolean> useColors;
+    private final Provider<Boolean> plainConsole;
 
     public NativeImageCommandLineProvider(Provider<NativeImageOptions> options,
                                           Provider<String> executableName,
@@ -93,15 +93,15 @@ public NativeImageCommandLineProvider(Provider<NativeImageOptions> options,
                                           Provider<RegularFile> classpathJar,
                                           Provider<Boolean> useArgFile,
                                           Provider<Integer> majorJDKVersion,
-                                          Provider<Boolean> useColors) {
+                                          Provider<Boolean> plainConsole) {
         this.options = options;
         this.executableName = executableName;
         this.workingDirectory = workingDirectory;
         this.outputDirectory = outputDirectory;
         this.classpathJar = classpathJar;
         this.useArgFile = useArgFile;
         this.majorJDKVersion = majorJDKVersion;
-        this.useColors = useColors;
+        this.plainConsole = plainConsole;
     }
 
     @Nested
@@ -192,8 +192,10 @@ public List<String> asArguments() {
         appendBooleanOption(cliArgs, options.getVerbose(), NativeImageFlags.VERBOSE);
         appendBooleanOption(cliArgs, options.getSharedLibrary(), NativeImageFlags.SHARED);
         appendBooleanOption(cliArgs, options.getQuickBuild(), NativeImageFlags.QUICK_BUILD);
-        if (useColors.get()) {
-            appendBooleanOption(cliArgs, options.getRichOutput(), majorJDKVersion.getOrElse(-1) >= 21 ? NativeImageFlags.COLOR : NativeImageFlags.BUILD_OUTPUT_COLORFUL);
+        if (plainConsole.get()) {
+            cliArgs.add(majorJDKVersion.getOrElse(-1) >= 21 ? NativeImageFlags.COLOR + "=never" : NativeImageFlags.BUILD_OUTPUT_COLORLESS);
+        } else {
+            appendBooleanOption(cliArgs, options.getRichOutput(), majorJDKVersion.getOrElse(-1) >= 21 ? NativeImageFlags.COLOR + "=always" : NativeImageFlags.BUILD_OUTPUT_COLORFUL);
         }
         appendBooleanOption(cliArgs, options.getPgoInstrument(), NativeImageFlags.PGO_INSTRUMENT);
 

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

@@ -55,6 +55,7 @@
 import org.gradle.api.file.FileSystemOperations;
 import org.gradle.api.file.RegularFile;
 import org.gradle.api.file.RegularFileProperty;
+import org.gradle.api.logging.configuration.ConsoleOutput;
 import org.gradle.api.model.ObjectFactory;
 import org.gradle.api.plugins.JavaBasePlugin;
 import org.gradle.api.provider.MapProperty;
@@ -95,7 +96,7 @@
 public abstract class BuildNativeImageTask extends DefaultTask {
     private final Provider<String> graalvmHomeProvider;
     private final NativeImageExecutableLocator.Diagnostics diagnostics;
-    private final boolean useColors;
+    private final boolean plainConsole;
 
     @Internal
     public abstract Property<NativeImageOptions> getOptions();
@@ -271,7 +272,7 @@ public BuildNativeImageTask() {
         ProviderFactory providers = getProject().getProviders();
         this.diagnostics = new NativeImageExecutableLocator.Diagnostics();
         this.graalvmHomeProvider = graalvmHomeProvider(providers, diagnostics);
-        this.useColors = "plain".equals(getProject().getGradle().getStartParameter().getConsoleOutput());
+        this.plainConsole = ConsoleOutput.Plain.equals(getProject().getGradle().getStartParameter().getConsoleOutput());
         getDisableToolchainDetection().convention(false);
     }
 
@@ -287,7 +288,7 @@ private List<String> buildActualCommandLineArgs(int majorJDKVersion) {
             getClasspathJar(),
             getUseArgFile(),
             getProviders().provider(() -> majorJDKVersion),
-            getProviders().provider(() -> useColors))
+            getProviders().provider(() -> plainConsole))
             .asArguments();
     }
 

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

@@ -186,4 +186,71 @@ class NativeImageCommandLineProviderTest extends AbstractPluginTest {
         args.contains("-cp")
         args.contains(appJar.absolutePath)
     }
+    // Plain Gradle consoles disable Native Image colors with version-appropriate arguments. §FS-native-invocation.3
+    @Issue("https://github.com/graalvm/native-build-tools/issues/366")
+    def "disables colorful Native Image output for Gradle's plain console with JDK #nativeImageVersion"() {
+        given:
+        def project = newProject()
+        project.plugins.apply(ApplicationPlugin)
+        project.plugins.apply(NativeImagePlugin)
+        def options = project.extensions.getByType(GraalVMExtension).binaries.getByName("main")
+        options.richOutput.set(true)
+        options.excludeConfigArgs.set([])
+        options.configurationFileDirectories.setFrom([])
+
+        when:
+        def args = new NativeImageCommandLineProvider(
+                project.provider { options },
+                project.provider { "main" },
+                project.provider { testDirectory.toString() },
+                project.provider { testDirectory.toString() },
+                project.objects.fileProperty(),
+                project.provider { false },
+                project.provider { nativeImageVersion },
+                project.provider { true }
+        ).asArguments()
+
+        then:
+        args.contains(disabledColorArgument)
+        !args.contains(NativeImageFlags.BUILD_OUTPUT_COLORFUL)
+
+        where:
+        nativeImageVersion | disabledColorArgument
+        17                 | NativeImageFlags.BUILD_OUTPUT_COLORLESS
+        21                 | "--color=never"
+    }
+
+    // Rich Gradle output enables Native Image colors with version-appropriate arguments. §FS-native-invocation.3
+    @Issue("https://github.com/graalvm/native-build-tools/issues/366")
+    def "uses the rich-output setting when Gradle enables colors with JDK #nativeImageVersion"() {
+        given:
+        def project = newProject()
+        project.plugins.apply(ApplicationPlugin)
+        project.plugins.apply(NativeImagePlugin)
+        def options = project.extensions.getByType(GraalVMExtension).binaries.getByName("main")
+        options.richOutput.set(true)
+        options.excludeConfigArgs.set([])
+        options.configurationFileDirectories.setFrom([])
+
+        when:
+        def args = new NativeImageCommandLineProvider(
+                project.provider { options },
+                project.provider { "main" },
+                project.provider { testDirectory.toString() },
+                project.provider { testDirectory.toString() },
+                project.objects.fileProperty(),
+                project.provider { false },
+                project.provider { nativeImageVersion },
+                project.provider { false }
+        ).asArguments()
+
+        then:
+        args.contains(enabledColorArgument)
+        !args.contains(NativeImageFlags.BUILD_OUTPUT_COLORLESS)
+
+        where:
+        nativeImageVersion | enabledColorArgument
+        17                 | NativeImageFlags.BUILD_OUTPUT_COLORFUL
+        21                 | "--color=always"
+    }
 }

native-maven-plugin/docs/functional/native-image-builds.md

@@ -66,3 +66,10 @@ mvn -Pnative -DquickBuild native:test
 mvn -Pnative native:write-args-file
 mvn -Pnative native:list-libraries-missing-metadata
 ```
+
+## 9. Console colors
+
+The native-image invocation must follow Maven's detected console color state. It must use
+`--color=always` or `--color=never` on JDK 21 and later, and `-H:+BuildOutputColorful` or
+`-H:-BuildOutputColorful` on older versions. Explicit user build arguments come later and may
+override this detected default, adapting [§root/FS-native-builds.2](../../../docs/spec/functional/native-image-builds.md#2-command-line-construction).

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

@@ -41,17 +41,20 @@
 
 package org.graalvm.buildtools.maven
 
+import org.graalvm.buildtools.utils.NativeImageUtils
 import spock.lang.Issue
 
 import static org.graalvm.buildtools.utils.SharedConstants.NATIVE_IMAGE_EXE;
 
 class JavaApplicationFunctionalTest extends AbstractGraalVMMavenFunctionalTest {
+    // Maven's disabled console colors propagate to Native Image. §FS-native-builds.9, §E2E-functional-tests.3.1.
     def "proper options are added to the native-image invocation"() {
         withSample("java-application")
 
         when:
         mvn '-Pnative', '-DskipTests', '-DnativeDryRun', '-DuseArgFile=false',
                 '-Dclasspath=/', '-Ddebug', '-Dfallback=false', '-Dverbose', '-DsharedLibrary',
+                '-Dstyle.color=never',
                 '-DquickBuild',
                 'package'
 
@@ -60,6 +63,8 @@ class JavaApplicationFunctionalTest extends AbstractGraalVMMavenFunctionalTest {
         outputContains NATIVE_IMAGE_EXE
         outputContains "-cp " // actual path is OS-specific (/ vs C:\)
         outputContains "-g --no-fallback --verbose --shared -Ob"
+        def majorVersion = NativeImageUtils.getMajorJDKVersion(GraalVMSupport.getGraalVMHomeVersionString())
+        outputContains(majorVersion >= 21 ? "--color=never" : "-H:-BuildOutputColorful")
     }
 
     def "can build and execute a native image with the Maven plugin"() {

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

@@ -51,6 +51,7 @@
 import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.maven.project.MavenProject;
 import org.apache.maven.toolchain.ToolchainManager;
+import org.apache.maven.shared.utils.logging.MessageUtils;
 import org.codehaus.plexus.logging.Logger;
 import org.graalvm.buildtools.maven.config.ExcludeConfigConfiguration;
 import org.graalvm.buildtools.model.resources.NativeImageFlags;
@@ -246,6 +247,8 @@ protected List<String> getBuildArgs() throws MojoExecutionException {
             cliArgs.add("-Ob");
         }
 
+        addConsoleColorArgument(cliArgs);
+
         cliArgs.add("-o");
         cliArgs.add(outputDirectory.toPath().toAbsolutePath() + File.separator + imageName);
 
@@ -297,6 +300,26 @@ protected List<String> getBuildArgs() throws MojoExecutionException {
         return Collections.unmodifiableList(actualCliArgs);
     }
 
+    // Maven's detected console mode controls version-appropriate Native Image color flags. §FS-native-builds.9.
+    private void addConsoleColorArgument(List<String> cliArgs) throws MojoExecutionException {
+        boolean colorEnabled = isColorEnabled();
+        if (getNativeImageMajorVersion() >= 21) {
+            cliArgs.add(NativeImageFlags.COLOR + (colorEnabled ? "=always" : "=never"));
+        } else {
+            cliArgs.add(colorEnabled ? NativeImageFlags.BUILD_OUTPUT_COLORFUL : NativeImageFlags.BUILD_OUTPUT_COLORLESS);
+        }
+    }
+
+    protected boolean isColorEnabled() {
+        return MessageUtils.isColorEnabled();
+    }
+
+    protected int getNativeImageMajorVersion() throws MojoExecutionException {
+        Path executable = NativeImageConfigurationUtils.getNativeImageSupportingToolchain(
+                logger, toolchainManager, session, enforceToolchain);
+        return NativeImageUtils.getMajorJDKVersion(getVersionInformation(logger, executable));
+    }
+
     static List<String> processBuildArgs(List<String> buildArgs) {
         var result = new ArrayList<String>();
         for (String buildArg : buildArgs) {
@@ -578,7 +601,14 @@ protected static String getVersionInformation(Logger logger) throws MojoExecutio
             return nativeImageVersionInformation;
         }
 
-        Path nativeImageExecutable = NativeImageConfigurationUtils.getNativeImage(logger);
+        return getVersionInformation(logger, NativeImageConfigurationUtils.getNativeImage(logger));
+    }
+
+    private static String getVersionInformation(Logger logger, Path nativeImageExecutable) throws MojoExecutionException {
+        if (nativeImageVersionInformation != null) {
+            return nativeImageVersionInformation;
+        }
+
         try {
             ProcessBuilder processBuilder = new ProcessBuilder(nativeImageExecutable.toString());
             processBuilder.command().add("--version");