Skip to content

Commit

Permalink
Remove documentation encouraging the use of json config 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 discourage Quarkus users from creating
their own configuration files.
  • Loading branch information
zakkak committed Oct 16, 2023
1 parent 2a2e719 commit 643fdae
Showing 1 changed file with 0 additions and 133 deletions.
133 changes: 0 additions & 133 deletions docs/src/main/asciidoc/writing-native-applications-tips.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -55,72 +55,6 @@ 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.

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:

[source,json]
----
{
"resources": [
{
"pattern": ".*\\.xml$"
},
{
"pattern": ".*\\.json$"
}
]
}
----

The patterns are valid Java regexps.
Here we include all the XML files and JSON files into the native executable.

[NOTE]
====
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:ResourceConfigurationFiles=resources-config.json
----

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.

[TIP]
====
Multiple options may be separated by a comma. For example, one could use:
[source,properties]
----
quarkus.native.additional-build-args =\
-H:ResourceConfigurationFiles=resources-config.json,\
-H:ReflectionConfigurationFiles=reflection-config.json
----
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:ResourceConfigurationFiles=resources-config.json</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 Expand Up @@ -223,73 +157,6 @@ public class MyReflectionConfiguration {
}
----

==== Using a configuration file

You can use a configuration file to register classes for reflection.

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

[source,json]
----
[
{
"name" : "com.acme.MyClass",
"allDeclaredConstructors" : true,
"allPublicConstructors" : true,
"allDeclaredMethods" : true,
"allPublicMethods" : true,
"allDeclaredFields" : true,
"allPublicFields" : true
}
]
----

[NOTE]
====
For more information about the format of this file, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/dynamic-features/Reflection/[GraalVM Reflection 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:ReflectionConfigurationFiles=reflection-config.json
----

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.

[TIP]
====
Multiple options may be separated by a comma. For example, one could use:
[source,properties]
----
quarkus.native.additional-build-args =\
-H:ResourceConfigurationFiles=resources-config.json,\
-H:ReflectionConfigurationFiles=reflection-config.json
----
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:ReflectionConfigurationFiles=reflection-config.json</quarkus.native.additional-build-args>
</properties>
</profile>
</profiles>
----

[[delay-class-init-in-your-app]]
=== Delaying class initialization

Expand Down

0 comments on commit 643fdae

Please sign in to comment.