Skip to content

Commit

Permalink
Update documentation about using GraalVM configuration files
Browse files Browse the repository at this point in the history 
Starting with Mandrel 23.1 and GraalVM for JDK 21 the use of
`-H:ResourceConfigurationFiles` and `-H:ReflectionConfigurationFiles` is
marked as experimental and requires the use of
`-H::±UnlockExperimentalVMOptions` to avoid warnings (see
oracle/graal#7190), while in the future (planned for the next release)
the presence of this option will be mandatory when using experimental
options (see oracle/graal#7370).

Furthermore, as described in oracle/graal#7487 Mandrel and GraalVM will also adopt glob patterns in the future (planned for the next release) and gradually phase out the ability to use exclude patterns.

The aim of this change is to inform Quarkus users that they are
responsible for keeping such configuration files up to date and to make
clear that they need to start using the
`-H::±UnlockExperimentalVMOptions` option.
  • Loading branch information
@zakkak
zakkak committed Oct 16, 2023
1 parent a90d6d5 commit 975871c
Showing 1 changed file with 52 additions and 8 deletions.
60 changes: 52 additions & 8 deletions docs/src/main/asciidoc/writing-native-applications-tips.adoc
View file
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,

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

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"}
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.

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"}

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

0 comments on commit 975871c

Please sign in to comment.