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 @@
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 @@
* 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,

Check warning on line 62 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 62, "column": 1}}}, "severity": "INFO"}

Check warning on line 62 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 62, "column": 65}}}, "severity": "INFO"}
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.

Check warning on line 63 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 63, "column": 123}}}, "severity": "INFO"}

[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.

Check warning on line 67 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 67, "column": 116}}}, "severity": "INFO"}

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.

Check warning on line 69 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 69, "column": 13}}}, "severity": "INFO"}
====

An example of such a file is the following:

[source,json]
----
Expand Down Expand Up @@ -84,9 +97,18 @@

[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`.

Check warning on line 108 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 108, "column": 44}}}, "severity": "INFO"}
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,11 +119,13 @@
[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.

Check warning on line 128 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'to' rather than 'in order to' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'to' rather than 'in order to' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 128, "column": 1}}}, "severity": "WARNING"}

Check warning on line 128 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 128, "column": 1}}}, "severity": "INFO"}

====
If for some reason adding the aforementioned configuration to `application.properties` is not desirable, it is possible to configure the build tool to effectively perform the same operation.
Expand All @@ -115,7 +139,9 @@
<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,9 +251,14 @@

==== 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.

Check warning on line 258 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 258, "column": 116}}}, "severity": "INFO"}
====

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`)

Check warning on line 261 in docs/src/main/asciidoc/writing-native-applications-tips.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'in order to'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 261, "column": 16}}}, "severity": "INFO"}

[source,json]
----
Expand All @@ -253,9 +284,18 @@

[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 @@
[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 @@
<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
Loading