Skip to content

Clarify that buildArgs entries are native-image argument tokens #930

Description

@jormundur00

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.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions