Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation about using GraalVM configuration files #36491

Merged
merged 1 commit into from
Oct 16, 2023
Merged

Update documentation about using GraalVM configuration files #36491

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 52 additions & 8 deletions docs/src/main/asciidoc/writing-native-applications-tips.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ So this directory is not a shortcut for "let's automatically include these resou
Other resources should be declared explicitly.
====

==== Using the `quarkus.native.resources.includes` configuration property

To include more resources in the native executable, the easiest way is to use the `quarkus.native.resources.includes` configuration property,
and its counterpart to exclude resources `quarkus.native.resources.excludes`.

Expand All @@ -55,8 +57,19 @@ will include:
* all files in the `foo/` directory and its subdirectories except for files in `foo/private/` and its subdirectories,
* all text files in the `bar/` directory and its subdirectories.

==== Using a configuration file

If globs are not sufficiently precise for your use case and you need to rely on regular expressions, or if you prefer relying on the GraalVM infrastructure,
you can also create a `resources-config.json` (the most common location is within `src/main/resources`) JSON file defining which resources should be included:
you can also create a `resources-config.json` (the most common location is within `src/main/resources`) JSON file defining which resources should be included.

[WARNING]
====
Relying on the GraalVM infrastructure means that you are responsible for keeping the configuration file up to date as new Mandrel and GraalVM versions are released.

Please also note that the `resources-config.json` file will be overwritten by Quarkus if placed directly under `src/main/resources/META-INF/native-image/` as Quarkus generates its own configuration file in this directory.
====

An example of such a file is the following:

[source,json]
----
Expand Down Expand Up @@ -84,9 +97,18 @@ The final order of business is to make the configuration file known to the `nati

[source,properties]
----
quarkus.native.additional-build-args =-H:ResourceConfigurationFiles=resources-config.json
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this option entirely gone or it's just that you need to stick to conventions and let GraalVM detect them?

Same question for the other option below.

Asking because IIRC, using these files could be useful/more flexible but maybe that's not the case anymore?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this option entirely gone or it's just that you need to stick to conventions and let GraalVM detect them?

The latter. There is no plan to remove these options in the foreseeable future, but users should not be encouraged to use them as they can change or get removed anytime.

Asking because IIRC, using these files could be useful/more flexible but maybe that's not the case anymore?

For resources, this files are going to move to "glob patterns" any way, meaning that even if someone relies on the added flexibility at some point they won't be able to use them.

Regarding reflection I believe that io.quarkus.runtime.annotations.RegisterForReflection covers most cases, and if there are some not covered we could work in extending it instead of asking users to create their own config files.

As a more defensive approach we could keep the docs and add a warning that the way the config files are used is planned to change and users should refrain from using them.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal would have been to keep the content, remove the mention of the option and enforce the file name.

But I can see your point too. So I let you decide what you prefer. If you prefer your PR as is, let me know and I'll merge it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal would have been to keep the content, remove the mention of the option and enforce the file name.

That's not going to work, at least not without changing the way it works now. Currently Quarkus copies all json config files in the jars it generates, but only uses them in the native-image if the user explicitly defines the said options. My understanding is that this is done to prevent unintended bloat.

But I can see your point too. So I let you decide what you prefer. If you prefer your PR as is, let me know and I'll merge it.

I have no strong opinion. The options I see are:

  1. This PR, were we drop the support of custom configs entirely.

  2. Leave the documentation as is and adding a note mentioning that this is an "on your own option" and whoever uses it is responsible to make sure the configuration files are compatible with the Mandrel or GraalVM version they use, as well as for making sure they pass any additional flags to avoid warnings and build errors.

  3. Allow for custom configurations that we integrate in the json configuration files that Quarkus generates anyway, this will remove the need for using ResourceConfigurationFiles and ReflectionConfigurationFiles but will complicate the code handling the corresponding annotations and the generation of the json config files.

I think I prefer 2. Let me work on it and submit another PR.

quarkus.native.additional-build-args =\
-H:+UnlockExperimentalVMOptions,\
-H:ResourceConfigurationFiles=resources-config.json,\
-H:-UnlockExperimentalVMOptions
----

[NOTE]
====
Starting with Mandrel 23.1 and GraalVM for JDK 21, `-H:ResourceConfigurationFiles=resources-config.json` results in a warning being shown unless wrapped in `-H:+UnlockExperimentalVMOptions` and `-H:-UnlockExperimentalVMOptions`.
The absence of these options will result in build failures in the future.
====

In the previous snippet we were able to simply use `resources-config.json` instead of specifying the entire path of the file simply because it was added to `src/main/resources`.
If the file had been added to another directory, the proper file path would have had to be specified manually.

Expand All @@ -97,8 +119,10 @@ Multiple options may be separated by a comma. For example, one could use:
[source,properties]
----
quarkus.native.additional-build-args =\
-H:+UnlockExperimentalVMOptions,\
-H:ResourceConfigurationFiles=resources-config.json,\
-H:ReflectionConfigurationFiles=reflection-config.json
-H:ReflectionConfigurationFiles=reflection-config.json,\
-H:-UnlockExperimentalVMOptions
----

in order to ensure that various resources are included and additional reflection is registered.
Expand All @@ -115,7 +139,9 @@ When using Maven, we could use the following configuration:
<id>native</id>
<properties>
<quarkus.package.type>native</quarkus.package.type>
<quarkus.native.additional-build-args>-H:ResourceConfigurationFiles=resources-config.json</quarkus.native.additional-build-args>
<quarkus.native.additional-build-args>
-H:+UnlockExperimentalVMOptions,-H:ResourceConfigurationFiles=resources-config.json,-H:-UnlockExperimentalVMOptions
</quarkus.native.additional-build-args>
</properties>
</profile>
</profiles>
Expand Down Expand Up @@ -225,7 +251,12 @@ public class MyReflectionConfiguration {

==== Using a configuration file

You can use a configuration file to register classes for reflection.
You can also use a configuration file to register classes for reflection, if you prefer relying on the GraalVM infrastructure.

[WARNING]
====
Relying on the GraalVM infrastructure means that you are responsible for keeping the configuration file up to date as new Mandrel and GraalVM versions are released.
====

As an example, in order to register all methods of class `com.acme.MyClass` for reflection, we create `reflection-config.json` (the most common location is within `src/main/resources`)

Expand Down Expand Up @@ -253,9 +284,18 @@ The final order of business is to make the configuration file known to the `nati

[source,properties]
----
quarkus.native.additional-build-args =-H:ReflectionConfigurationFiles=reflection-config.json
quarkus.native.additional-build-args =\
-H:+UnlockExperimentalVMOptions,\
-H:ReflectionConfigurationFiles=reflection-config.json,\
-H:-UnlockExperimentalVMOptions
----

[NOTE]
====
Starting with Mandrel 23.1 and GraalVM for JDK 21, `-H:ResourceConfigurationFiles=resources-config.json` results in a warning being shown unless wrapped in `-H:+UnlockExperimentalVMOptions` and `-H:-UnlockExperimentalVMOptions`.
The absence of these options will result in build failures in the future.
====

In the previous snippet we were able to simply use `reflection-config.json` instead of specifying the entire path of the file simply because it was added to `src/main/resources`.
If the file had been added to another directory, the proper file path would have had to be specified manually.

Expand All @@ -266,8 +306,10 @@ Multiple options may be separated by a comma. For example, one could use:
[source,properties]
----
quarkus.native.additional-build-args =\
-H:+UnlockExperimentalVMOptions,\
-H:ResourceConfigurationFiles=resources-config.json,\
-H:ReflectionConfigurationFiles=reflection-config.json
-H:ReflectionConfigurationFiles=reflection-config.json,\
-H:-UnlockExperimentalVMOptions
----

in order to ensure that various resources are included and additional reflection is registered.
Expand All @@ -284,7 +326,9 @@ When using Maven, we could use the following configuration:
<id>native</id>
<properties>
<quarkus.package.type>native</quarkus.package.type>
<quarkus.native.additional-build-args>-H:ReflectionConfigurationFiles=reflection-config.json</quarkus.native.additional-build-args>
<quarkus.native.additional-build-args>
-H:+UnlockExperimentalVMOptions,-H:ReflectionConfigurationFiles=reflection-config.json,-H:-UnlockExperimentalVMOptions
</quarkus.native.additional-build-args>
</properties>
</profile>
</profiles>
Expand Down