From 481986aba61b388f81ab4485fec2a961d32e30e8 Mon Sep 17 00:00:00 2001 From: Foivos Zakkak Date: Thu, 7 Sep 2023 11:56:45 +0300 Subject: [PATCH] Adapt documentation to new GraalVM version scheme and doc links Closes #34929 --- docs/pom.xml | 6 ++++-- docs/src/main/asciidoc/_attributes.adoc | 6 +++--- .../src/main/asciidoc/building-native-image.adoc | 4 ++-- docs/src/main/asciidoc/cdi-reference.adoc | 2 +- docs/src/main/asciidoc/gradle-tooling.adoc | 2 +- docs/src/main/asciidoc/maven-tooling.adoc | 2 +- docs/src/main/asciidoc/native-and-ssl.adoc | 2 +- docs/src/main/asciidoc/native-reference.adoc | 10 +++++----- .../writing-native-applications-tips.adoc | 16 ++++++++-------- 9 files changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/pom.xml b/docs/pom.xml index 43da6420781c56..5d8fd796d6c594 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -17,8 +17,10 @@ - jdk-17 - jdk-17 + for JDK 17 + jdk17 + jdk-17 + jdk-17 3.5.0 2.0.0 diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/src/main/asciidoc/_attributes.adoc index 93aef07b2194ad..b4b1fa66834172 100644 --- a/docs/src/main/asciidoc/_attributes.adoc +++ b/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} diff --git a/docs/src/main/asciidoc/building-native-image.adoc b/docs/src/main/asciidoc/building-native-image.adoc index 89065b22499fb5..b29f6bb8799e1c 100644 --- a/docs/src/main/asciidoc/building-native-image.adoc +++ b/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 or , 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. diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc index 45165171358b97..08af52f56e101e 100644 --- a/docs/src/main/asciidoc/cdi-reference.adoc +++ b/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. diff --git a/docs/src/main/asciidoc/gradle-tooling.adoc b/docs/src/main/asciidoc/gradle-tooling.adoc index 8d58477cb0ef5e..6452911c757046 100644 --- a/docs/src/main/asciidoc/gradle-tooling.adoc +++ b/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: diff --git a/docs/src/main/asciidoc/maven-tooling.adoc b/docs/src/main/asciidoc/maven-tooling.adoc index 739945d18e0256..f0e278d80f2ef4 100644 --- a/docs/src/main/asciidoc/maven-tooling.adoc +++ b/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 <>. Create a native executable using: diff --git a/docs/src/main/asciidoc/native-and-ssl.adoc b/docs/src/main/asciidoc/native-and-ssl.adoc index 2a0f744fef173f..f61b72f2f230b4 100644 --- a/docs/src/main/asciidoc/native-and-ssl.adoc +++ b/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 diff --git a/docs/src/main/asciidoc/native-reference.adoc b/docs/src/main/asciidoc/native-reference.adoc index 43021f2c9b7097..80acfde8fac390 100644 --- a/docs/src/main/asciidoc/native-reference.adoc +++ b/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? diff --git a/docs/src/main/asciidoc/writing-native-applications-tips.adoc b/docs/src/main/asciidoc/writing-native-applications-tips.adoc index 82149c66e3da19..b3e58ed1336585 100644 --- a/docs/src/main/asciidoc/writing-native-applications-tips.adoc +++ b/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=` 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