Merge pull request quarkusio#47883 from zakkak/2025-05-15-implement-47762

Introduce property `quarkus.native.additional-build-args-append`

Author: zakkak

core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java

@@ -42,6 +42,16 @@ public interface NativeConfig {
      */
     Optional<List<String>> additionalBuildArgs();
 
+    /**
+     * Comma-separated, additional arguments to pass to the build process.
+     * The arguments are appended to those provided through {@link #additionalBuildArgs()}, as a result they may override those
+     * passed through {@link #additionalBuildArgs()}.
+     * By convention, this is meant to be set on the command-line, while {@link #additionalBuildArgs()} should be preferred for
+     * use in properties files.
+     * If an argument includes the {@code ,} symbol, it needs to be escaped, e.g. {@code \\,}
+     */
+    Optional<List<String>> additionalBuildArgsAppend();
+
     /**
      * If the HTTP url handler should be enabled, allowing you to do URL.openConnection() for HTTP URLs
      */

core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/NativeImageBuildStep.java

@@ -800,7 +800,8 @@ public NativeImageInvokerInfo build() {
                      * Instruct GraalVM / Mandrel to keep more accurate information about source locations when generating
                      * debug info for debugging and monitoring tools. This parameter may break compatibility with Truffle.
                      * Affected users should explicitly pass {@code -H:-TrackNodeSourcePosition} through
-                     * {@code quarkus.native.additional-build-args} to override it.
+                     * {@code quarkus.native.additional-build-args} or {@code quarkus.native.additional-build-args-append}
+                     * to override it.
                      *
                      * See https://github.com/quarkusio/quarkus/issues/30772 for more details.
                      */
@@ -849,8 +850,9 @@ public NativeImageInvokerInfo build() {
 
                 /*
                  * Any parameters following this call are forced over the user provided parameters in
-                 * quarkus.native.additional-build-args. So if you need a parameter to be overridable through
-                 * quarkus.native.additional-build-args please make sure to add it before this call.
+                 * quarkus.native.additional-build-args or quarkus.native.additional-build-args-append. So if you need
+                 * a parameter to be overridable through quarkus.native.additional-build-args or
+                 * quarkus.native.additional-build-args-append please make sure to add it before this call.
                  */
                 handleAdditionalProperties(nativeImageArgs);
 
@@ -1061,8 +1063,13 @@ public NativeImageInvokerInfo build() {
             }
 
             private void handleAdditionalProperties(List<String> command) {
-                if (nativeConfig.additionalBuildArgs().isPresent()) {
-                    List<String> strings = nativeConfig.additionalBuildArgs().get();
+                Optional<List<String>>[] additionalBuildArgs = new Optional[] { nativeConfig.additionalBuildArgs(),
+                        nativeConfig.additionalBuildArgsAppend() };
+                for (Optional<List<String>> args : additionalBuildArgs) {
+                    if (args.isEmpty()) {
+                        continue;
+                    }
+                    List<String> strings = args.get();
                     for (String buildArg : strings) {
                         String trimmedBuildArg = buildArg.trim();
                         if (trimmedBuildArg.contains(TRUST_STORE_SYSTEM_PROPERTY_MARKER) && containerBuild) {

core/deployment/src/test/java/io/quarkus/deployment/pkg/TestNativeConfig.java

@@ -35,6 +35,11 @@ public Optional<List<String>> additionalBuildArgs() {
         return Optional.empty();
     }
 
+    @Override
+    public Optional<List<String>> additionalBuildArgsAppend() {
+        return Optional.empty();
+    }
+
     @Override
     public boolean enableHttpUrlHandler() {
         return false;

docs/src/main/asciidoc/building-native-image.adoc

@@ -192,10 +192,10 @@ If you have generated the application from the previous tutorial, you can find i
 
 [TIP]
 ====
-You can provide custom options for the `native-image` command using the `<quarkus.native.additional-build-args>` property.
+You can provide custom options for the `native-image` command using the `quarkus.native.additional-build-args` and `quarkus.native.additional-build-args-append` properties.
 Multiple options may be separated by a comma.
 
-Another possibility is to include the `quarkus.native.additional-build-args` configuration property in your `application.properties`.
+By convention `quarkus.native.additional-build-args-append` is meant to be defined at the command line (e.g. `-Dquarkus.native.additional-build-args-append=--verbose`), while `quarkus.native.additional-build-args` may be defined either at the command line or in your `application.properties`. Note that, any arguments included in `quarkus.native.additional-build-args-append` may override those included in `quarkus.native.additional-build-args`.
 
 You can find more information about how to configure the native image building process in the <<configuration-reference>> section below.
 ====