Deprecate fallback plugin options

[jormundur00]

What changed

The Gradle fallback DSL option and Maven <fallback> parameter are now marked deprecated. Both remain available for compatibility.

The plugins now distinguish the GraalVM release from the JDK version reported by native-image --version:

• Before GraalVM 25.1, disabling fallback continues to generate --no-fallback.
• On positively identified GraalVM 25.1+ releases, the plugins omit the generated --no-fallback flag.
• Runtime-environment lines are parsed independently of vendor labels, covering Oracle GraalVM, Mandrel, and BellSoft Liberica NIK formats.
• If the GraalVM release cannot be identified, the plugins conservatively retain the flag.
• Explicit user-supplied --no-fallback build arguments remain unchanged.

Why

Native Image removed the fallback feature in GraalVM 25.1, so --no-fallback is deprecated and has no effect there. Suppressing the plugin-generated flag avoids a deprecation warning on every build while preserving behavior for older GraalVM releases.

Both GraalVM 25.0 and 25.1 use JDK 25, so the existing JDK-major check cannot distinguish them. The implementation reads the first dotted release from a runtime-environment line in the existing native-image --version output, regardless of the distribution's vendor label, and does not add another version-check process.

Example

Existing configurations continue to work while showing the deprecation in API documentation:

nativeImage {
    fallback = false // deprecated on GraalVM 25.1+
}

<configuration>
  <fallback>false</fallback> <!-- deprecated on GraalVM 25.1+ -->
</configuration>

Implementation summary

• Added deprecation annotations and GraalVM 25.1 guidance to the Gradle and Maven option surfaces.
• Added shared, vendor-neutral GraalVM release detection independent of the JDK version.
• Suppressed plugin-generated --no-fallback on confirmed GraalVM 25.1+ releases in both plugins.
• Preserved compatibility behavior for older and unrecognized releases and preserved explicit build arguments.
• Updated the common, Gradle, and Maven functional specs.
• Added exact Oracle GraalVM, Mandrel, and BellSoft Liberica NIK parser fixtures, including same-format 25.1 cases.
• Added Gradle/Maven command-line regression tests.

Validation

• grund check
• grund fmt . --marker --cross-refs --check
• ./gradlew :utils:check
• Focused Gradle and Maven argument regression tests
• Maven invocation functional test against real Oracle GraalVM 25.0.3, Mandrel 25.0.3.0-Final, and BellSoft Liberica NIK 25.0.3-2 installations
• Verified real current outputs are identified as pre-25.1 and same-format 25.1 transformations are identified as 25.1+ for all three distributions
• ./gradlew :native-gradle-plugin:inspections :native-maven-plugin:inspections :utils:check
• git diff --check
• A complete Maven unit run was attempted for the original deprecation change; it has one unrelated reproducible NativeExtensionTest failure because this environment lacks a Spock class-mocking backend. The changed Maven tests and module inspections passed.

Fixes #991

[vjovanov]

I would test this with Mandrel and Bellsoft distributions.

[jormundur00]

@vjovanov Thanks for the suggestion. Adding Mandrel and Liberica NIK as permanent CI dimensions would significantly increase the number and cost of CI jobs, so I tested them locally instead.

I tested the parser and Maven command invocation against actual installations of:

• Oracle GraalVM 25.0.3
• Mandrel 25.0.3.0-Final
• BellSoft Liberica NIK 25.0.3-2

Mandrel uses OpenJDK Runtime Environment ..., whereas Oracle GraalVM and Liberica NIK use GraalVM Runtime Environment .... I loosened the parser to recognize the first dotted release on any Runtime Environment line, independently of the vendor label, and added the exact outputs as regression-test fixtures.

I also tested same-format 25.1 variants for all three distributions. Assuming they retain their current output structure, they are recognized as 25.1+ and the plugin-generated --no-fallback is omitted.

An unknown distribution using a different version-output structure remains conservative: it will retain --no-fallback, even on 25.1. The build should still work because the option remains accepted as deprecated and without effect, but it may print the deprecation warning.

We could avoid the version-specific omission entirely if this approach is considered too heuristic, but then builds using the default disabled-fallback configuration would print the --no-fallback deprecation warning on every GraalVM 25.1 build. I think the current conservative approach gives us the better tradeoff.

[vjovanov]

No need to add to the CI, just test. Excellent!