Proposal: Add -H:Preserve support via the shared ArtifactSelection model

[vjovanov]

Note

This is a design proposal for discussion — not an accepted plan or committed work. It sketches a direction and its trade-offs so the approach can be reviewed before anyone implements it. Scope, DSL/XML surface, and naming are all open to change. Depends on #977.

Summary

Add first-class support for -H:Preserve (keeping classes reachable that closed-world analysis would otherwise drop) by reusing the ArtifactSelection model from #977 — no new selection vocabulary. The build-tool value is resolving dependency coordinates to path= entries; the all / bare module=/package= cases remain on the build-args pass-through.

Motivation

-H:Preserve shares LayerCreate's grammar exactly:

-H:Preserve=all
-H:Preserve=module=<m>,package=<p>,path=<jar>

The genuinely build-tool part — "preserve everything from dependency com.acme:extension and its closure" — cannot be written as a static buildArgs entry, because path=<jar> is computed by dependency resolution. That is the justification for a first-class surface; without resolution there is nothing to add over pass-through.

There is currently no tracking issue and no code for Preserve in NBT — it is greenfield on both. Introducing it after #977 means it reuses a proven model rather than inventing a parallel one.

Proposal

Reuse ArtifactSelection and add a renderPreserve(ArtifactSelection) in common/. Surface the same selector block used by layer contents:

binaries {
    main {
        preserve {
            dependencies("com.acme:extension")   // resolved → path=  (the build-tool value)
            packages("com.acme.plugins")         // dynamically-loaded plugin package
            // all()                              // = -H:Preserve=all
        }
    }
}

<preserve>
  <dependencies><dependency>com.acme:extension</dependency></dependencies>
  <packages><package>com.acme.plugins</package></packages>
  <!-- <all>true</all> -->
</preserve>

Both preserve blocks deserialize into the same ArtifactSelection bean and render through the same common code path (so escaping and arg-file conversion are identical).

Spec alignment

Spec links pinned to commit e067164.

• NGOAL-no-flag-mirroring: first-class only for the dependency-selection dimension (needs resolution); all and bare module/package ride buildArgs/<buildArgs>. Because the selection model is shared with layers, this judgment call is made once and inherited.
• FS-common-libraries.1 / GOAL-plugin-parity: rendering in common/, symmetric Gradle/Maven surfaces.

Depends on

• Proposal: Uplift the layers configuration model (typed model, shared selection, Gradle+Maven parity) #977 — requires the ArtifactSelection type and the plugin-side coordinate→path resolution. Should not start until Proposal: Uplift the layers configuration model (typed model, shared selection, Gradle+Maven parity) #977's selection model exists.

Related

• Allow all classes from a JAR, Module, or Package to be Included for Reflection #558 (Allow all classes from a JAR/Module/Package for reflection) — same jar/module/package vocabulary; a candidate third consumer of ArtifactSelection. Worth cross-linking so the shared model isn't scoped to just layers+preserve.

Deliverables

• renderPreserve(ArtifactSelection) in common/ + unit tests.
• Gradle preserve { } block on binaries.
• Maven <preserve> config on the compile goals.
• Functional test: preserve an individual dependency + its closure, verify a type that analysis would drop survives.

Open question

Scope Preserve per-binary only (matches how it's used), or also allow it on a created layer's contents? Recommend per-binary first; revisit if a use case appears.

[jvukicev]

Implementation proposal

Scope

Implement first-class -H:Preserve support only for the capability Native Build Tools adds beyond raw Native Image arguments: selecting a Gradle or Maven dependency coordinate and resolving that dependency, optionally with its transitive closure, to concrete path= selectors.

The Gradle surface will be binary-scoped and available to the existing main, test, custom, and shared-library binary option objects. The Maven surface will apply to application-image compilation through compile, compile-no-fork, and the deprecated build alias. Preserve configuration will be opt-in and will not change invocations that omit it.

The first-class Gradle and Maven surfaces will expose dependency selection only. They will not expose all, module, package, or explicit-path selectors, because those values require no build-tool resolution and remain available through buildArgs or <buildArgs>. Preserve configuration inside named layer contents, native-test Maven goals, resource/reflection support from issue 558, and unrelated layer-model changes are out of scope.

Repository and specification constraints

The change is spec-first. Before production code, extend the root cross-plugin native-build and parity specifications, the common shared-utility specification, the Gradle binary/invocation specifications, and the Maven configuration/build-goal specifications. Add or update a decision point clarifying that ArtifactSelection is a build-tool-neutral selector value that may be consumed by more than layer rendering, while layer task and artifact wiring remains governed by the existing layer decision.

The design must preserve §root/NGOAL-no-flag-mirroring by limiting public Preserve configuration to dependency-coordinate resolution. It must preserve §root/GOAL-plugin-parity and §root/FS-plugin-common.1 by offering equivalent dependency-selection behavior in build-tool-native syntax, and §root/FS-native-builds.2 by routing rendering and argument-file conversion through common utilities. Common code must remain free of Gradle, Maven, Aether, project, task, configuration, and artifact types under §common/REQ-no-buildtool-apis.

Gradle resolution must remain lazy and provider-safe under §gradle/FS-plugin-model.2. Maven must use its resolved project dependency graph and normal configuration model under §maven/FS-config-model.1. Existing layer DSL/XML, public constructors and methods, raw build arguments, command ordering, and builds without Preserve configuration must remain compatible. Every changed spec, internal source, and test must carry the most-specific valid grund citation required by the repository rules, followed by workspace-wide citation validation.

Intended behavior and file changes

In common/utils, generalize the documentation and validation language of ArtifactSelection so it is no longer described as layer-only without changing its package or constructor contract. Add the Preserve flag constant to NativeImageFlags and introduce a build-tool-neutral NativeImagePreserveArguments.renderPreserve(ArtifactSelection) renderer. The renderer will serialize the Native Image Preserve grammar in deterministic selector order, reject an empty selection, and use the same path and argument-file handling conventions as existing shared argument utilities. It may render the complete shared model for internal reuse, but the plugin adapters added by this issue will populate only resolved paths.

In the Gradle plugin, add a nested preserve configuration to NativeImageCompileOptions and its concrete/delegating implementations. Add a focused PreserveConfiguration DSL type with dependency-coordinate methods matching the established layer dependency semantics: transitive resolution by default, an explicit non-transitive option, and provider-backed catalog dependencies where supported. Reuse or extract the existing Gradle artifact-view resolution mechanics so selected artifacts remain lazy task inputs. NativeImageCommandLineProvider will convert the resolved files to a path-only ArtifactSelection and append one rendered Preserve argument before user-supplied build arguments. A configured but empty selection, blank coordinates, or failed dependency resolution will fail before Native Image starts with a Preserve-specific diagnostic. Unit tests will cover DSL wiring, laziness, transitivity, command construction, and unchanged behavior when Preserve is absent.

In the Maven plugin, add PreserveConfiguration and dependency-entry configuration classes for <preserve><dependencies>...</dependencies></preserve>. Attach the parameter to the application compile mojo hierarchy so it covers compile, compile-no-fork, and the deprecated build alias without implicitly enabling native-test or layer-create goals. Extract or reuse the coordinate parsing and dependency-trail matching currently used for layer selection, preserving version-qualified matching, configured transitivity, stable de-duplication, reactor outputs, and resolved artifact paths. The compile invocation will create a path-only ArtifactSelection, render one Preserve argument before user <buildArgs>, and report blank, missing, ambiguous, empty, or fileless selections as normal Maven execution errors.

Update the corresponding root, common, Gradle, and Maven functional/E2E specifications and user documentation with symmetric dependency-only examples. The documentation will explicitly direct raw all, module, package, and explicit-path Preserve forms to build arguments, state the default transitive-closure behavior, describe the image-size implications, and list the supported Gradle binary and Maven goal matrix.

Validation strategy

Run workspace-wide grund validation and repository formatting after the spec and citation updates. Exercise the common utility tests for path-only, all, module, package, mixed, ordering, empty-selection, platform-path, and argument-file cases, while separately asserting that the new plugin DSL/XML exposes dependencies only.

Run focused Gradle unit tests for binary-model wiring, provider-backed dependency notation, transitive and non-transitive resolution, task input tracking, command ordering, empty/error diagnostics, and main/test/custom/shared-library option coverage. Add a Gradle functional fixture in which a selected dependency and a transitive dependency contain a type that ordinary closed-world analysis would not retain, then verify the configured binary can load or otherwise observe that type while a control build demonstrates the Preserve behavior is material.

Run focused Maven unit tests for XML mapping, compile-goal coverage, coordinate/version matching, dependency-trail closure, de-duplication, reactor artifact paths, command ordering, and diagnostics. Add the equivalent Maven functional fixture for the application compile path and verify that native-test and layer-create executions do not gain the new parameter unintentionally. Compare the rendered dependency paths and transitivity behavior across both plugins, then run the relevant common, Gradle, Maven, and aggregate test suites supported by the repository and available Native Image test environment.

Risks and mitigations

The exact Preserve grammar, release availability, and experimental-option requirements may differ across GraalVM versions. Verify them against the supported Native Image versions before finalizing code and tests; if the feature cannot fit the repository support policy without a material design change, stop and request a revised proposal rather than adding an undocumented compatibility gate.

Dependency-closure matching can drift between Gradle and Maven. Reuse the established layer-selection semantics within each adapter, document a shared scenario matrix, and cover direct, transitive, non-transitive, version-qualified, reactor, duplicate, and missing selections in both implementations.

Paths may contain spaces, separators, or platform-specific syntax, and Preserve arguments may pass through argument files. Keep serialization in common, avoid adapter-specific string assembly, and test representative Windows and Unix path forms.

Preserving a dependency closure can increase reachability, build time, and image size. Keep selection explicit and binary-scoped, document transitivity and cost, allow non-transitive selection, and avoid an implicit preserve-all mode.

Generalizing a layer-named model or resolver could accidentally break the merged layer API. Retain existing public layer entry points and behavior, prefer additive helpers or compatibility-preserving extraction, and rerun all layer renderer, DSL/XML, and functional coverage alongside the new tests.

Known gaps

The intake evidence does not establish the minimum supported GraalVM release for -H:Preserve, whether it requires experimental-option unlock/lock arguments, or which CI images currently provide it. These facts must be confirmed during implementation before choosing version diagnostics and functional-test gating.

The exact functional fixture and observation mechanism must be selected after confirming current Native Image Preserve semantics; it must prove preservation of an otherwise-unreachable class rather than merely inspect a generated command line.

This proposal intentionally does not add first-class all, module, package, or explicit-path selectors, Preserve configuration for created-layer contents, or Preserve support to Maven native-test/integration-test goals. Those additions require separate workflow justification and approval if concrete use cases arise.

---

Proposal ID: ed75f3d55176ebb0

Approve:

/rhei approve ed75f3d55176ebb0

Reject with an explanation on following lines:

/rhei reject ed75f3d55176ebb0
<explain what should change>

This implementation proposal was generated by AI using openai:gpt-5.6-sol through Rhei.

[jvukicev]

/rhei approve ed75f3d55176ebb0