Skip to content

Commit

Permalink
Update native configuration file best practices
Browse files Browse the repository at this point in the history 
* Update to promote best ways to use custom configuration files.
  • Loading branch information
@galderz
galderz committed Feb 2, 2024
1 parent aec0d69 commit ff63dd6
Showing 1 changed file with 3 additions and 55 deletions.
58 changes: 3 additions & 55 deletions docs/src/main/asciidoc/writing-native-applications-tips.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,9 @@ will include:
==== 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 `resource-config.json` (the most common location is within `src/main/resources`) JSON file defining which resources should be included.
you can also create a `resource-config.json` 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": 64}}}, "severity": "INFO"}
Ideally this, and other native image configuration files, should be placed under the `src/main/resources/META-INF/native-image/<group-id>/<artifact-id>` folder.
By placing them there, there is no additional configuration parameters that need to be passed into the native build.

Check warning on line 65 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": 65, "column": 77}}}, "severity": "INFO"}

[WARNING]
====
Expand Down Expand Up @@ -93,60 +95,6 @@ Here we include all the XML files and JSON files into the native executable.
For more information about this topic, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/dynamic-features/Resources/[GraalVM Accessing Resources in Native Image] guide.
====

The final order of business is to make the configuration file known to the `native-image` executable by adding the proper configuration to `application.properties`:

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

[NOTE]
====
Starting with Mandrel 23.1 and GraalVM for JDK 21, `-H:ResourceConfigurationFiles=resource-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 `resource-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.

[TIP]
====
Multiple options may be separated by a comma. For example, one could use:
[source,properties]
----
quarkus.native.additional-build-args =\
-H:+UnlockExperimentalVMOptions,\
-H:ResourceConfigurationFiles=resource-config.json,\
-H:ReflectionConfigurationFiles=reflect-config.json,\
-H:-UnlockExperimentalVMOptions
----
in order to ensure that various resources are included and additional reflection is registered.
====
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.

When using Maven, we could use the following configuration:

[source,xml]
----
<profiles>
<profile>
<id>native</id>
<properties>
<quarkus.package.type>native</quarkus.package.type>
<quarkus.native.additional-build-args>
-H:+UnlockExperimentalVMOptions,-H:ResourceConfigurationFiles=resource-config.json,-H:-UnlockExperimentalVMOptions
</quarkus.native.additional-build-args>
</properties>
</profile>
</profiles>
----

=== Registering for reflection

When building a native executable, GraalVM operates with a closed world assumption.
Expand Down

0 comments on commit ff63dd6

Please sign in to comment.