Add stable option for -H:IncludeResources and -H:ExcludeResources

[jerboaa]

Describe the issue
With a GraalVM dev build (24.0) when -H:IncludeResources=path/to/image.jpg is being used it gets flagged as an experimental option. For example, in my case it produces the following warnings on the native-image invocation:

Warning: The option '-H:IncludeResources=Grace_M._Hopper.jp2,MyFreeMono.ttf,MyFreeSerif.ttf' is experimental and must be enabled via '-H:+UnlockExperimentalVMOptions' in the future.
Warning: Please re-evaluate whether any experimental option is required, and either remove or unlock it. The build output lists all active experimental options, including where they come from and possible alternatives. If you think an experimental option should be considered as stable, please file an issue.

As per the suggestion, I'm filing this issue to consider this as an API option. Or otherwise, how would one add resources to the image in 23.1+ without running into the experimental options issue?

[jerboaa]

/cc @fniephaus

[fniephaus]

Hi @jerboaa, thanks for raising this.

-H:IncludeResources can be replaced with an appropriate resource-config.json file.

So

-H:IncludeResources=Grace_M._Hopper.jp2,MyFreeMono.ttf,MyFreeSerif.ttf

can be turned into the following resource-config.json file:

{
  "resources": {
    "includes": [
      {
        "pattern": "Grace_M._Hopper.jp2"
      },
      {
        "pattern": "MyFreeMono.ttf"
      },
      {
        "pattern": "MyFreeSerif.ttf"
      }
    ]
  }
}

I'm sure you can come up with a smarter pattern if you prefer that.

[zakkak]

@jerboaa also note that this is how Quarkus handles this (it generates a resource-config.json file). If you get the above message with Quarkus then it's probably due to a third party dependency passing the argument (e.g. by setting Args in native-image.properties)

[fniephaus]

The build output tells you where the option is coming from:

 1 experimental option(s) unlocked:
 - '-H:IncludeResources' (origin(s): command line)

So in this case, it seems to be a user-provided command-line argument.

[jerboaa]

It seems a step backwards in terms of usability? First I need to generate a json, and then pass it to the native-image build using some other option? It would be nice if the driver could handle that for me.

[fniephaus]

We don't have any API options to register elements for reflection, JNI, etc. Why would we have that for resources? You don't need to add any additional option if the resource-config.json is in a META-INF/native-image/packagename/ location on your classpath or module path.

[fniephaus]

It seems a step backwards in terms of usability?

You can spin this both ways: with the config file, there is only one way to do the thing. We also provide tooling for the config files (e.g., for merging).

[jerboaa]

Fair enough. Could I convince you to make this apparent in the build output? A link to a doc should suffice. I.e. to safe the next person from going down the rabbit whole of trying to figure out what the replacement is supposed to be.

[fniephaus]

Could I convince you to make this apparent in the build output?

You don't have to convince me. 😉 The build output already prints alternative API options when available, but we didn't have time to implement support for more complex migration suggestions. The easiest solution in this case would be to deprecate IncludeResources and add the migration hint as a deprecationMessage. I'm not 100% sure this is what we actually want to do. Any thoughts?