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

Adapt documentation to new GraalVM version scheme and doc links #35795

Merged
merged 1 commit into from
Sep 19, 2023
Merged

Adapt documentation to new GraalVM version scheme and doc links #35795

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/pom.xml
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,10 +97,10 @@
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.

Check warning on line 103 in docs/src/main/asciidoc/building-native-image.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.", "location": {"path": "docs/src/main/asciidoc/building-native-image.adoc", "range": {"start": {"line": 103, "column": 187}}}, "severity": "INFO"}
** Use platform-specific install tools like https://sdkman.io/jdks#Oracle[sdkman], https://github.com/graalvm/homebrew-tap[homebrew], or https://github.com/ScoopInstaller/Java[scoop].
2. Configure the runtime environment. Set `GRAALVM_HOME` environment variable to the GraalVM installation directory, for example:
+
Expand Down Expand Up @@ -233,7 +233,7 @@
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,9 +413,9 @@

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

Check warning on line 416 in docs/src/main/asciidoc/gradle-tooling.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'verify' rather than 'Make sure' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'verify' rather than 'Make sure' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/gradle-tooling.adoc", "range": {"start": {"line": 416, "column": 1}}}, "severity": "WARNING"}

Create a native executable using:

Check warning on line 418 in docs/src/main/asciidoc/gradle-tooling.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/gradle-tooling.adoc", "range": {"start": {"line": 418, "column": 27}}}, "severity": "INFO"}

include::{includes}/devtools/build-native.adoc[]

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/maven-tooling.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,12 +392,12 @@

== Building a native executable

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

Check warning on line 395 in docs/src/main/asciidoc/maven-tooling.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'verify' rather than 'Make sure' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'verify' rather than 'Make sure' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/maven-tooling.adoc", "range": {"start": {"line": 395, "column": 89}}}, "severity": "WARNING"}

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

Check warning on line 398 in docs/src/main/asciidoc/maven-tooling.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/maven-tooling.adoc", "range": {"start": {"line": 398, "column": 55}}}, "severity": "INFO"}

Create a native executable using:

Check warning on line 400 in docs/src/main/asciidoc/maven-tooling.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/maven-tooling.adoc", "range": {"start": {"line": 400, "column": 27}}}, "severity": "INFO"}

include::{includes}/devtools/build-native.adoc[]

Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/native-and-ssl.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,8 +253,8 @@

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

Check warning on line 256 in docs/src/main/asciidoc/native-and-ssl.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JVM' rather than 'jvm'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JVM' rather than 'jvm'.", "location": {"path": "docs/src/main/asciidoc/native-and-ssl.adoc", "range": {"start": {"line": 256, "column": 183}}}, "severity": "INFO"}
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@

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

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

[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,10 +361,10 @@

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

Check warning on line 367 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.Headings] Use sentence-style capitalization in 'Modularity Benefits'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Modularity Benefits'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 367, "column": 5}}}, "severity": "INFO"}

During native executable build time GraalVM analyses the application's call tree and generates a code-set that includes all the code it needs.
Having a modular codebase is key to avoiding problems with unused or optional parts of your application,
Expand Down Expand Up @@ -613,7 +613,7 @@

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

[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,10 +658,10 @@

[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

Check warning on line 664 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.Headings] Use sentence-style capitalization in 'Managing Proxy Classes'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Managing Proxy Classes'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 664, "column": 5}}}, "severity": "INFO"}

Very similarly, Quarkus allows extensions authors to register a `NativeImageProxyDefinitionBuildItem`. An example of doing so is:

Expand All @@ -682,10 +682,10 @@

[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

Check warning on line 688 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.Headings] Use sentence-style capitalization in 'Logging with Native Image'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Logging with Native Image'.", "location": {"path": "docs/src/main/asciidoc/writing-native-applications-tips.adoc", "range": {"start": {"line": 688, "column": 5}}}, "severity": "INFO"}

If you are using dependencies that require logging components such as Apache Commons Logging or Log4j and are experiencing a `ClassNotFoundException` when building the native executable, you can resolve this by excluding the logging library and adding the corresponding JBoss Logging adapter.

Expand Down