Merge pull request #35795 from zakkak/2023-09-07-fix-34929

Adapt documentation to new GraalVM version scheme and doc links

docs/pom.xml

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

docs/src/main/asciidoc/_attributes.adoc

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

docs/src/main/asciidoc/building-native-image.adoc

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

docs/src/main/asciidoc/cdi-reference.adoc

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

docs/src/main/asciidoc/gradle-tooling.adoc

@@ -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:
 

docs/src/main/asciidoc/maven-tooling.adoc

@@ -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:

docs/src/main/asciidoc/native-and-ssl.adoc

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

docs/src/main/asciidoc/native-reference.adoc

@@ -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.
 
@@ -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]]
@@ -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.
@@ -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
@@ -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?
 

docs/src/main/asciidoc/writing-native-applications-tips.adoc

@@ -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`:
@@ -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`:
@@ -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]
@@ -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
@@ -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
@@ -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.
 ====
 
 
@@ -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
@@ -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