Skip to content

Commit

Permalink
Merge pull request quarkusio#35795 from zakkak/2023-09-07-fix-34929
Browse files Browse the repository at this point in the history
Adapt documentation to new GraalVM version scheme and doc links
  • Loading branch information
Sanne authored Sep 19, 2023
2 parents 5e9372d + 096e7c2 commit fe16659
Show file tree
Hide file tree
Showing 9 changed files with 26 additions and 24 deletions.
6 changes: 4 additions & 2 deletions docs/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,10 @@
<properties>
<!-- The Graal version we suggest using in documentation - as that's
what we work with by self downloading it: -->
<graal-community.version-for-documentation>jdk-17</graal-community.version-for-documentation>
<mandrel.version-for-documentation>jdk-17</mandrel.version-for-documentation>
<graal-community.version-for-documentation>for JDK 17</graal-community.version-for-documentation>
<graal-community.tag-for-documentation>jdk17</graal-community.tag-for-documentation>
<graal-community.image-tag-for-documentation>jdk-17</graal-community.image-tag-for-documentation>
<mandrel.image-tag-for-documentation>jdk-17</mandrel.image-tag-for-documentation>

<assembly-maven-plugin.version>3.5.0</assembly-maven-plugin.version>
<asciidoctor-maven-plugin.version>2.0.0</asciidoctor-maven-plugin.version>
Expand Down
6 changes: 3 additions & 3 deletions docs/src/main/asciidoc/_attributes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
// .
:maven-version: ${proposed-maven-version}
:graalvm-version: ${graal-community.version-for-documentation}
:graalvm-flavor: ${graal-community.version-for-documentation}
:mandrel-version: ${mandrel.version-for-documentation}
:mandrel-flavor: ${mandrel.version-for-documentation}
:graalvm-docs-version: ${graal-community.tag-for-documentation}
:graalvm-flavor: ${graal-community.image-tag-for-documentation}
:mandrel-flavor: ${mandrel.image-tag-for-documentation}
:surefire-version: ${version.surefire.plugin}
:gradle-version: ${gradle-wrapper.version}
:elasticsearch-version: ${elasticsearch-server.version}
Expand Down
4 changes: 2 additions & 2 deletions docs/src/main/asciidoc/building-native-image.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ If you cannot install GraalVM, you can use a multi-stage Docker build to run Mav
There is an explanation of how to do this at <<#multistage-docker,the end of this guide>>.
====

Version {graalvm-version} is required.
GraalVM {graalvm-version} is required.

1. Install GraalVM if you haven't already. You have a few options for this:
** Download the appropriate archive from <https://github.com/graalvm/mandrel/releases> or <https://github.com/graalvm/graalvm-ce-builds/releases>, and unpack it like you would any other JDK.
Expand Down Expand Up @@ -233,7 +233,7 @@ You can do so by prepending the flag with `-J` and passing it as additional nati
IMPORTANT: Fully static native executables support is experimental.

On Linux it's possible to package a native executable that doesn't depend on any system shared library.
There are link:https://www.graalvm.org/latest/reference-manual/native-image/guides/build-static-executables/#prerequisites-and-preparation[some system requirements] to be fulfilled and additional build arguments to be used along with the `native-image` invocation, a minimum is `-Dquarkus.native.additional-build-args="--static","--libc=musl"`.
There are link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/guides/build-static-executables/#prerequisites-and-preparation[some system requirements] to be fulfilled and additional build arguments to be used along with the `native-image` invocation, a minimum is `-Dquarkus.native.additional-build-args="--static","--libc=musl"`.

Compiling fully static binaries is done by statically linking https://musl.libc.org/[musl] instead of `glibc` and should not be used in production without rigorous testing.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/cdi-reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ quarkus.arc.exclude-dependency.acme.artifact-id=acme-services <2>
== Native Executables and Private Members
Quarkus is using GraalVM to build a native executable.
One of the limitations of GraalVM is the usage of link:https://www.graalvm.org/latest/reference-manual/native-image/Reflection/[Reflection, window="_blank"].
One of the limitations of GraalVM is the usage of link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/Reflection/[Reflection, window="_blank"].
Reflective operations are supported but all relevant members must be registered for reflection explicitly.
Those registrations result in a bigger native executable.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/gradle-tooling.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,7 @@ Once executed, you will be able to safely run quarkus task with `--offline` flag

Native executables make Quarkus applications ideal for containers and serverless workloads.

Make sure to have `GRAALVM_HOME` configured and pointing to the latest release of GraalVM version {graalvm-version}.
Make sure to have `GRAALVM_HOME` configured and pointing to the latest release of GraalVM {graalvm-version}.

Create a native executable using:

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/maven-tooling.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,7 @@ This goal will resolve all the runtime, build time, test and dev mode dependenci

Native executables make Quarkus applications ideal for containers and serverless workloads.

Make sure to have `GRAALVM_HOME` configured and pointing to the latest release of GraalVM version {graalvm-version}.
Make sure to have `GRAALVM_HOME` configured and pointing to the latest release of GraalVM {graalvm-version}.
Verify that your `pom.xml` has the proper `native` profile as shown in <<build-tool-maven>>.

Create a native executable using:
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/native-and-ssl.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -254,7 +254,7 @@ The file containing the custom TrustStore does *not* (and probably should not) h
=== Run time configuration

Using the runtime certificate configuration, supported by GraalVM since 21.3 does not require any special or additional configuration compared to regular java programs or Quarkus in jvm mode.
For more information, see the link:https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/CertificateManagement/#runtime-options[Runtime Options] section of the "GraalVM Certificate Management in Native Image" guide.
For more information, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/dynamic-features/CertificateManagement/#runtime-options[Runtime Options] section of the "GraalVM Certificate Management in Native Image" guide.

[#working-with-containers]
=== Working with containers
Expand Down
10 changes: 5 additions & 5 deletions docs/src/main/asciidoc/native-reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ These are the high level sections to be found in this guide:
== Native Memory Management
Memory management for Quarkus native executables is enabled by GraalVM’s SubstrateVM runtime system.

For detailed explanations about the memory management component in GraalVM, see the link:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/MemoryManagement[GraalVM Memory Management] guide.
For detailed explanations about the memory management component in GraalVM, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/MemoryManagement[GraalVM Memory Management] guide.

This guide complements the information available in the GraalVM website with further observations particularly relevant to Quarkus applications.

Expand Down Expand Up @@ -96,7 +96,7 @@ To build Quarkus native with epsilon GC, pass the following argument at build ti
----

=== Memory Management Options
For information about options to control maximum heap size, young space, and other typical use cases found in the JVM, see the link:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/MemoryManagement[GraalVM Memory Management] guide.
For information about options to control maximum heap size, young space, and other typical use cases found in the JVM, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/MemoryManagement[GraalVM Memory Management] guide.
Setting the maximum heap size, either as a percentage or an explicit value, is generally recommended.

[[gc-logging]]
Expand Down Expand Up @@ -234,7 +234,7 @@ $ ps -o pid,rss,command -p $(pidof code-with-quarkus-1.0.0-SNAPSHOT-runner)

How come this Quarkus native executable consumes ~35MB RSS on startup?
To get an understanding of this number, this section will use `perf` to trace calls to `syscalls:sys_enter_mmap`.
Assuming the default link:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/MemoryManagement/#serial-garbage-collector[GraalVM Serial Garbage Collector] is in use, this system call is particularly interesting for native executables generated by GraalVM's `native-image` because of how it allocates heap.
Assuming the default link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/MemoryManagement/#serial-garbage-collector[GraalVM Serial Garbage Collector] is in use, this system call is particularly interesting for native executables generated by GraalVM's `native-image` because of how it allocates heap.
In native executables generated by GraalVM's `native-image`, the heap is allocated using either aligned or unaligned heap chunks.
All non-array objects get allocated in thread local aligned chunks.
Each of these are 1MB in size by default.
Expand Down Expand Up @@ -1863,7 +1863,7 @@ We can now examine line `169` and get a first hint of what might be wrong
(in this case we see that it fails at the first read from src which contains the address `0x0000`),
or walk up the stack using `gdb`’s `up` command to see what part of our code led to this situation.
For more information about using `gdb` to debug native executables, see the
link:https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/DebugInfo/[GraalVM Debug Info Feature] guide.
link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/debugging-and-diagnostics/DebugInfo/[GraalVM Debug Info Feature] guide.

[[native-faq]]
== Frequently Asked Questions
Expand Down Expand Up @@ -2185,7 +2185,7 @@ Once the image is compiled, enable and start JFR via runtime flags: `-XX:+Flight
-XX:StartFlightRecording="filename=recording.jfr"
----

For more information about using JFR, see the link:https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/JFR/[GraalVM JDK Flight Recorder (JFR) with Native Image] guide.
For more information about using JFR, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/debugging-and-diagnostics/JFR/[GraalVM JDK Flight Recorder (JFR) with Native Image] guide.

=== How can we troubleshoot performance problems only reproducible in production?

Expand Down
16 changes: 8 additions & 8 deletions docs/src/main/asciidoc/writing-native-applications-tips.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ 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/latest/reference-manual/native-image/dynamic-features/Resources/[GraalVM Accessing Resources in Native Image] guide.
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`:
Expand Down Expand Up @@ -245,7 +245,7 @@ As an example, in order to register all methods of class `com.acme.MyClass` for

[NOTE]
====
For more information about the format of this file, see the link:https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/[GraalVM Reflection in Native Image] guide.
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`:
Expand Down Expand Up @@ -327,7 +327,7 @@ It should be added to the `native-image` configuration using the `quarkus.native

[NOTE]
====
For more information, see the link:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/ClassInitialization/[GraalVM Class Initialization in Native Image] guide.
For more information, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/ClassInitialization/[GraalVM Class Initialization in Native Image] guide.
====

[NOTE]
Expand Down Expand Up @@ -361,7 +361,7 @@ com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfac

Solving this issue requires adding the `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>` option and to provide a dynamic proxy configuration file.

For more information about the format of this file, see the link:https://www.graalvm.org/latest/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually] guide.
For more information about the format of this file, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually] guide.

[[modularity-benefits]]
=== Modularity Benefits
Expand Down Expand Up @@ -613,7 +613,7 @@ public class SaxParserProcessor {

[NOTE]
====
For more information about reflection in GraalVM, see the link:https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/[GraalVM Reflection in Native Image] guide.
For more information about reflection in GraalVM, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/dynamic-features/Reflection/[GraalVM Reflection in Native Image] guide.
====

=== Including resources
Expand All @@ -634,7 +634,7 @@ public class ResourcesProcessor {

[NOTE]
====
For more information about GraalVM resource handling in native executables, see the link:https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Resources/[GraalVM Accessing Resources in Native Image] guide.
For more information about GraalVM resource handling in native executables, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/dynamic-features/Resources/[GraalVM Accessing Resources in Native Image] guide.
====


Expand All @@ -658,7 +658,7 @@ Using such a construct means that a `--initialize-at-run-time` option will autom

[NOTE]
====
For more information about the `--initialize-at-run-time` option, see the link:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/ClassInitialization/[GraalVM Class Initialization in Native Image] guide.
For more information about the `--initialize-at-run-time` option, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/ClassInitialization/[GraalVM Class Initialization in Native Image] guide.
====

=== Managing Proxy Classes
Expand All @@ -682,7 +682,7 @@ Using such a construct means that a `-H:DynamicProxyConfigurationResources` opti

[NOTE]
====
For more information about Proxy Classes, see the link:https://www.graalvm.org/latest/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually] guide.
For more information about Proxy Classes, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually] guide.
====

=== Logging with Native Image
Expand Down

0 comments on commit fe16659

Please sign in to comment.