Add -H:Preserve dependency selection support

[jormundur00]

What changed

Native Build Tools now supports dependency-based -H:Preserve configuration for GraalVM 25 and later. Gradle binaries can select dependencies with preserve { dependencies(...) }, and Maven application compile goals can select them with <preserve><dependencies>...</dependencies></preserve>. Selected dependencies are resolved to concrete path= entries, including transitive dependencies by default.

Raw all, module, package, and explicit-path Preserve selectors remain available through existing build arguments.

Why

Native Image can otherwise discard code that is only reached dynamically. Dependency coordinates cannot be converted to Native Image path= selectors in a static build argument, so the plugins now resolve those coordinates while preserving the existing build-tool-neutral selector and rendering behavior.

Example

Gradle:

graalvmNative {
    binaries.main {
        preserve {
            dependencies('org.example:extension-api:1.0.0')
            dependencies('org.example:extension-runtime:1.0.0') {
                transitive = false
            }
        }
    }
}

Maven:

<preserve>
    <dependencies>
        <dependency>
            <artifact>org.example:extension-api:1.0.0</artifact>
        </dependency>
        <dependency>
            <artifact>org.example:extension-runtime:1.0.0</artifact>
            <transitive>false</transitive>
        </dependency>
    </dependencies>
</preserve>

Both configurations emit a path-based -H:Preserve argument before user-supplied build arguments. The feature applies to Gradle main, test, custom, and shared-library binaries and Maven compile, compile-no-fork, and deprecated build application goals.

Implementation summary

• Added deterministic Preserve rendering to common Native Image utilities.
• Added lazy, task-input-aware dependency selection to the Gradle binary model.
• Added Maven dependency selection using the resolved project graph, including reactor outputs and compile-goal ownership.
• Added focused unit tests, Gradle and Maven functional coverage, specifications, and user documentation.

Validation

• /tmp/grund-0.9.0.da1aRP/bin/grund check
• /tmp/grund-0.9.0.da1aRP/bin/grund fmt . --marker --cross-refs --check
• git diff --check
• ./gradlew :utils:test --tests org.graalvm.buildtools.utils.NativeImagePreserveArgumentsTest --rerun-tasks --console=plain
• ./gradlew :native-gradle-plugin:test --tests org.graalvm.buildtools.gradle.tasks.PreserveConfigurationTest --tests org.graalvm.buildtools.gradle.tasks.NativeImageCommandLineProviderTest --rerun-tasks --console=plain
• ./gradlew :native-maven-plugin:test --tests org.graalvm.buildtools.maven.PreserveConfigurationTest --tests org.graalvm.buildtools.maven.AbstractNativeImageMojoTest --rerun-tasks --console=plain
• GRAALVM_HOME="$JAVA_HOME" ./gradlew :native-gradle-plugin:functionalTest --tests org.graalvm.buildtools.gradle.PreserveDependencyFunctionalTest --rerun-tasks --console=plain
• GRAALVM_HOME="$JAVA_HOME" ./gradlew :native-maven-plugin:functionalTest --tests org.graalvm.buildtools.maven.PreserveDependencyFunctionalTest --rerun-tasks --console=plain
• ./gradlew :utils:checkstyleMain :utils:checkstyleTest :native-gradle-plugin:checkstyleMain :native-gradle-plugin:checkstyleTest :native-gradle-plugin:checkstyleFunctionalTest :native-maven-plugin:checkstyleMain :native-maven-plugin:checkstyleTest :native-maven-plugin:checkstyleFunctionalTest --rerun-tasks --console=plain
• Generated Maven descriptor inspection confirmed preserve is present only on build, compile, and compile-no-fork.

The focused checks passed on Oracle GraalVM/native-image 25.0.3. The full repository build, all-module suite, complete functional/CI matrices, other supported GraalVM versions, and documentation rendering were not rerun.

Fixes #978

AI workflow

Generated by Rhei’s github-issue-fix workflow using 8 completed AI-assisted steps, 2 resolved models, and 1 focused review cycle.

View AI workflow details

Approved proposal: ed75f3d55176ebb0.

1. Issue intake and routing

Resolved the issue scope, repository rules, grounding fit, isolated worktree, and approved implementation route.

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: high
Tokens: 1418916 total · 1401571 input (1303552 cached) · 17345 output

2. Implementation

Implemented dependency-based Preserve support across common utilities, Gradle, Maven, specifications, documentation, and tests.

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: high
Tokens: 9885728 total · 9857337 input (9629952 cached) · 28391 output

3. Validation visit — cycle 1

Ran the focused unit, functional, grounding, formatting, style, and generated-descriptor checks.

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: high
Tokens: 2495128 total · 2478431 input (2370560 cached) · 16697 output

4. Requirements review — cycle 1

Checked the implementation against the repository requirements and accepted proposal scope.

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: high
Tokens: 756174 total · 748620 input (648832 cached) · 7554 output

5. Specification review — cycle 1

Checked specification coverage, citation specificity, and grounded behavior declarations.

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: high
Tokens: 1193211 total · 1179204 input (1053056 cached) · 14007 output

6. Implementation review — cycle 1

Reviewed the changed implementation and tests for correctness, compatibility, and scope adherence.

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: high
Tokens: 5275460 total · 5256347 input (5059072 cached) · 19113 output

7. Validation review — cycle 1

Reviewed the validation evidence and confirmed there were no validation blockers.

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: high
Tokens: 322540 total · 316963 input (261120 cached) · 5577 output

8. Aggregate review — cycle 1

Combined the requirements, specification, implementation, and validation reviews and confirmed publication readiness.

Model: openai:gpt-5.6-sol · Agent: codex · Reasoning effort: high
Tokens: 116820 total · 114913 input (91008 cached) · 1907 output

9. Publish PR

Committed the reviewed work, pushed graalvm:rhei/issue-978 to origin, and created or updated the ready-for-review pull request.

Model: openai:gpt-5.6-luna · Agent: codex · Reasoning effort: high
Tokens: not finalized at PR creation

Aggregate token usage: 21463977 total · 21353386 input (20417152 cached) · 110591 output

The aggregate is partial and excludes the current unfinalized publication step. It uses the latest record for the retried implementation step; 1 superseded timed-out implementation attempt had unknown usage and is not counted separately. Review cycles: 1 focused, 0 repair. Accounting coverage: partial (8 measured records, 1 missing superseded attempt). Unsupported cache dimensions: output cached-read and output cache-write.