Document how and where to add custom GraalVM configuration files

[klopfdreh]

Version information

Spring Boot version: 3.3.4

Bug description

When you place a

• reflection-config.json
• proxy-config.json
• resource-config.json
• serialization-config.json

into

src/main/resources/META-INF/native-image/<groupid>/<artifactid>/

and you perform a process-aot with spring-boot-maven-plugin the configuration files that you have defined in your project are not merged with those the plugin is generating.

Instead the plugin overwrites the configuration which clashes with the documentation of https://www.graalvm.org/latest/reference-manual/native-image/metadata/.

The current workaround is that you have to write a RuntimeHintsRegistrar and define the definitions there.

@Configuration
@ImportRuntimeHints(MyRuntimeHints.class)
@Slf4j
public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
      //....
    }
}

With a RuntimeHintsRegistrar the plugin is adding the entries to the desired files.

[snicoll]

Instead the plugin overwrites the configuration which clashes with the documentation of https://www.graalvm.org/latest/reference-manual/native-image/metadata/.

What part of the doc clashes with this?

I think we're lacking some guidance in this area. It is true that our AOT infrastructure takes control and will generate metadata in src/main/resources/META-INF/native-image/<groupid>/<artifactid>/. These will end up in BOOT-INF/classes iin the repackaged archive.

If you decide to write manual metadata using the same namespace in the same module, they will be overwritten at the moment. You can use a different namespace for this, something like src/main/resources/META-INF/native-image//-manual/. Or you can write the metadata in a different module with its own artifactId and include that in your application. Have you tried any of that?

[klopfdreh]

What part of the doc clashes with this?

It is mentioned that in this folder GraalVM collect metadata for your application automatically.

If you decide to write manual metadata using the same namespace in the same module, they will be overwritten at the moment. You can use a different namespace for this, something like src/main/resources/META-INF/native-image//-manual/. Or you can write the metadata in a different module with its own artifactId and include that in your application. Have you tried any of that?

Sure this is working if you pack it into a separate dependency which is not using the spring-boot-maven-plugin and packed as "normal" jar, but this would require to split the project apart without any reason.

If you use a custom namespace this would require you to use -H:+UnlockExperimentalVMOptions for newer GraalVM versions and to add command line args like -H:ResourceConfigurationResources=META-INF/native-image/custom-definitions/resource-config.json for example to the native-image build and the resources are not picked up automatically.

[snicoll]

It is mentioned that in this folder GraalVM collect metadata for your application automatically.

Sorry I don't see how that section refers to the Spring Boot plugin or where it is said that manual metadata is merged automatically. Can you please quote exactly what you think implies that the Spring Boot plugin "clashes with the documentation"?

this would require to split the project apart without any reason.

For a start, I wasn't aware that GraalVM would let you pick any namespace you want in META-INF/native-image but would not support two. This looks quite strange to me.

Assuming that's what it does, the reason would be exactly that, GraalVM doesn't support picking up such resources from two locations automatically so you have to separate them or configure the plugin.

That's what I'd recommend for the time being anyway. As for merging manual input, we can consider it, I'll flag for team attention to get more feedback from the team.

[klopfdreh]

Sorry I don't see how that section refers to the Spring Boot plugin or where it is said that manual metadata is merged automatically. Can you please quote exactly what you think implies that the Spring Boot plugin "clashes with the documentation"?

So what I meant by this is that the GraalVM documentation explains that if you place the metadata configuration files in this specific folder they are automatically picked up. The spring-boot-maven-plugin however overwrites them and the configuration are not used anymore.

That's what I'd recommend for the time being anyway. As for merging manual input, we can consider it, I'll flag for team attention to get more feedback from the team.

Thanks a lot! 👍

Anyway - we found a workaround so it isn't urgent.

[mhalbritter]

If you use a custom namespace this would require you to use -H:+UnlockExperimentalVMOptions for newer GraalVM versions and to add command line args like -H:ResourceConfigurationResources=META-INF/native-image/custom-definitions/resource-config.json for example to the native-image build and the resources are not picked up automatically.

This is not what I'm seeing. I'm using Java version: 23+37, vendor version: Oracle GraalVM 23+37.1 and I can create META-INF/native-image/foo/bar/reachability-metadata.json and this is used in addition to the metadata the process-aot task has created. (where foo and bar is something different from my group id and artifact).

This also works with Java version: 17.0.12+8-LTS, vendor version: Oracle GraalVM 17.0.12+8.1 using reflect-config.json.

So what Stephane said:

You can use a different namespace for this, something like src/main/resources/META-INF/native-image//-manual/.

is true, isn't it?