The Maven and Gradle plugin docs should clarify how buildArgs entries map to Native Image options.
The important rule is that each configured entry should contain one Native Image option expression. The plugin configuration is not a shell command line, and users should not combine several independent Native Image options into one entry.
Some Native Image options include a value in the same expression, such as --emit build-report, --enable-monitoring=jfr, or -H:Name=value; those should stay in the documented Native Image form. The confusing case is a single entry that combines unrelated options, such as --static --libc=musl -H:+ReportExceptionStackTraces.
For example, Maven docs should prefer this shape:
<buildArgs>
<buildArg>--static</buildArg>
<buildArg>--libc=musl</buildArg>
<buildArg>--emit build-report</buildArg>
<buildArg>-H:+ReportExceptionStackTraces</buildArg>
</buildArgs>
and Gradle docs should show the equivalent:
buildArgs.addAll(
"--static",
"--libc=musl",
"--emit build-report",
"-H:+ReportExceptionStackTraces"
)
This would prevent confusion from examples or user configurations that treat buildArgs as a shell-style string, such as putting --static --libc=musl into one Maven <buildArg> entry.
Suggested docs locations:
docs/src/docs/asciidoc/maven-plugin.adoc, near the <buildArgs> section.
docs/src/docs/asciidoc/gradle-plugin.adoc, near the buildArgs.add(...) description.
The Maven and Gradle plugin docs should clarify how
buildArgsentries map to Native Image options.The important rule is that each configured entry should contain one Native Image option expression. The plugin configuration is not a shell command line, and users should not combine several independent Native Image options into one entry.
Some Native Image options include a value in the same expression, such as
--emit build-report,--enable-monitoring=jfr, or-H:Name=value; those should stay in the documented Native Image form. The confusing case is a single entry that combines unrelated options, such as--static --libc=musl -H:+ReportExceptionStackTraces.For example, Maven docs should prefer this shape:
and Gradle docs should show the equivalent:
buildArgs.addAll( "--static", "--libc=musl", "--emit build-report", "-H:+ReportExceptionStackTraces" )This would prevent confusion from examples or user configurations that treat
buildArgsas a shell-style string, such as putting--static --libc=muslinto one Maven<buildArg>entry.Suggested docs locations:
docs/src/docs/asciidoc/maven-plugin.adoc, near the<buildArgs>section.docs/src/docs/asciidoc/gradle-plugin.adoc, near thebuildArgs.add(...)description.