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

Jump to bottom

Update native configuration file best practices #38186

Merged
merged 2 commits into from
Feb 9, 2024
Merged

Update native configuration file best practices #38186

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff63dd6
Update native configuration file best practices
galderz Jan 15, 2024
c575a2d
Update docs/src/main/asciidoc/writing-native-applications-tips.adoc
galderz Feb 9, 2024
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
58 changes: 3 additions & 55 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 @@ -59,8 +59,10 @@

==== 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.
This way they will be automatically parsed by the native build, without additional configuration.

[WARNING]
====
Expand Down Expand Up @@ -93,60 +95,6 @@
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
Loading