[GR-59211] [GR-60094] [WIP] Documentation maintenance.

PullRequest: graal/19428

Author: olyagpl

docs/getting-started/macos.md

@@ -46,7 +46,7 @@ Install GraalVM from an archive (_.tar.gz_) for the current user into any locati
 
 3. Move the downloaded package to its proper location, the _/Library/Java/JavaVirtualMachines/_ directory. Since this is a system directory, `sudo` is required:
     ```bash
-    sudo mv graalvm-jdk-<version>_macos-<architecture> /Library/Java/JavaVirtualMachines
+    sudo mv graalvm-jdk-<version> /Library/Java/JavaVirtualMachines
     ```
     To verify if the move is successful and to get a list of all installed JDKs, run `/usr/libexec/java_home -V`.
 

docs/reference-manual/native-image/JFR.md

@@ -15,7 +15,7 @@ GraalVM Native Image supports building a native executable with JFR events, and
 
 JFR support is disabled by default and must be explicitly enabled at build time.
 
-> Note: JFR event recording is not yet available in GraalVM JDK on Windows.
+> Note: JFR event recording is not yet available with Native Image on Windows.
  
 To build a native executable with JFR, use the `--enable-monitoring=jfr` option:
 ```shell

docs/reference-manual/native-image/guides/add-logging-to-native-executable.md

@@ -12,12 +12,12 @@ By default, a native executable produced by Native Image supports logging via th
 
 ## Default Logging Configuration
 
-The default logging configuration in a native executable is based on the `logging.properties` file found in the JDK.
+The default logging configuration in a native executable is based on the _logging.properties_ file found in the JDK.
 This file configures a `java.util.logging.ConsoleHandler` which will only show messages at the `INFO` level and above.
-Custom logging configuration can be loaded either at build time or at runtime as described below.
+Custom logging configuration can be loaded either at build time or at run time as described below.
 
 If you require additional logging handlers, you must register the corresponding classes for reflection.
-For example, if you use `java.util.logging.FileHandler` then provide the following reflection configuration:
+For example, if you use `java.util.logging.FileHandler`, then provide the following reflection configuration in the _META-INF/native-image/reachability-metadata.json_ file:
 ```json
 {
     "name" : "java.util.logging.FileHandler",
@@ -26,6 +26,7 @@ For example, if you use `java.util.logging.FileHandler` then provide the followi
     ]
   }
 ```
+
 For more details, see [Reflection Support](../ReachabilityMetadata.md#reflection).
 
 The usage of the logger is shown in the following example:
@@ -64,10 +65,10 @@ The usage of the logger is shown in the following example:
     WARNING: Danger, Will Robinson! [Wed May 18 17:22:40 BST 2022]
     ```
 
-    In this case, the _logging.properties_ file needs to be available for runtime processing so it must be included into the _reachability-metadata.json_ file under the _META-INF/native-image/<group-id>_ folder. 
+    In this case, the _logging.properties_ file must be available for runtime processing and therefore needs to be registered in the _META-INF/native-image/reachability-metadata.json_ file.
     For more details on how to do this, see [Use of Resources in a Native Executable](../ReachabilityMetadata.md#resources).
 
 ### Related Documentation
 
 * [Reachability Metadata: Reflection](../ReachabilityMetadata.md#reflection)
-* [Native Image Build Configuration](../BuildConfiguration.md)
+* [Native Image Build Configuration](../BuildConfiguration.md)

docs/reference-manual/native-image/guides/build-and-run-native-executable-with-jfr.md

@@ -7,12 +7,12 @@ permalink: /reference-manual/native-image/guides/build-and-run-native-executable
 
 # Build and Run Native Executables with JFR
 
-[JDK Flight Recorder (JFR](https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm) is a tool for collecting diagnostic and profiling data about a running Java application, built into the JVM. 
+[JDK Flight Recorder (JFR)](https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm) is a tool for collecting diagnostic and profiling data about a running Java application, built into the JVM. 
 GraalVM Native Image supports JFR events and users can use the [`jdk.jfr.Event` API](https://docs.oracle.com/en/java/javase/22/docs/api/jdk.jfr/jdk/jfr/Event.html) with a similar experience to using JFR in the Java HotSpot VM.
 
 To collect JFR events when running a native executable, enable JFR support and JFR event recording as described in this guide.
 
-> Note: JFR event recording is not yet available in GraalVM JDK on Windows.
+> Note: JFR event recording is not yet available with Native Image on Windows.
 
 ## Enable JFR Support and Record Events at Runtime
 
@@ -52,13 +52,13 @@ For other installation options, visit the [Downloads section](https://www.graalv
     It creates an event, annotated with `@Label` from the `jdk.jfr.*` package.
     If you run this application, it will not print anything and just run that event.
 
-2. Compile the Java file using the GraalVM JDK:
+2. Ccompile the application using the GraalVM JDK:
     ```shell 
     javac JFRDemo.java
     ```
     It creates two class files: _JFRDemo$HelloWorldEvent.class_	and _JFRDemo.class_.
 
-3. Build a native executable with VM inspection enabled:
+3. Build a native executable with the VM inspection enabled:
     ```shell
     native-image --enable-monitoring=jfr JFRDemo
     ```
@@ -89,5 +89,4 @@ It will look something like this:
 
 ### Related Documentation
 
-- Learn more about [Native Image support for JFR events](../JFR.md) and how to further configure JFR recording and system logging.
-- [Create and record your first event with Java](https://docs.oracle.com/en/java/javase/22/jfapi/creating-and-recording-your-first-event.html).
+- Learn more about [Native Image support for JFR events](../JFR.md) and how to further configure JFR recording and system logging.

docs/reference-manual/native-image/guides/build-and-run-native-executable-with-remote-jmx.md

@@ -19,8 +19,8 @@ It also shows you how to register a custom managed bean (MBean) with the JMX ser
 A JMX connection from a client to a remote MBean server is supported. 
 The client, the server, or both may be a native executable.
 Only MXBeans, and standard user-defined MBeans, are supported. 
-Dynamic and model MBeans are not supported because their management interfaces are defined at runtime. 
-Although remote management of MXBeans is supported, not all platform MXBean functionality is implemented or is applicable in a native executable produced by Native Image. 
+Dynamic and model MBeans are not supported because their management interfaces are defined at run time. 
+Although remote management of MXBeans is supported, not all platform MXBean functionality is implemented or is applicable in a native executable. 
 Additionally, to define and use standard MBeans, you must specify metadata configuration. 
 This is further explained in this guide.
 
@@ -79,13 +79,13 @@ For other installation options, visit the [Downloads section](https://www.graalv
     }
     ```
 
-2. Change your working directory to where you saved the file. Then compile the application using the GraalVM JDK:
+2. Ccompile the application using the GraalVM JDK:
     ```shell 
     javac SimpleJmx.java
     ```
     This creates _SimpleJmx.class_, _SimpleJmx$Simple.class_, and _SimpleJmx$SimpleMBean.class_ files.
 
-3. Add dynamic proxy configuration. JMX uses dynamic proxies, a [dynamic feature](../DynamicFeatures.md) of Java, to access MBeans. To be able to interact with the custom `SimpleMBean` at runtime, you need to provide Native Image with additional [dynamic-proxy metadata](../ReachabilityMetadata.md#reflection) for the MBean interface. For this, create or modify a JSON file named _reachability-metadata.json_ with the following contents:
+3. Add dynamic proxy configuration. JMX uses dynamic proxies, a [dynamic feature](../DynamicFeatures.md) of Java, to access MBeans. To be able to interact with the custom `SimpleMBean` at run time, you need to provide Native Image with additional [dynamic-proxy metadata](../ReachabilityMetadata.md#reflection) for the MBean interface. For this, create or modify a JSON file named _reachability-metadata.json_ with the following contents:
     ```json
     {
       "reflection": [
@@ -98,7 +98,7 @@ For other installation options, visit the [Downloads section](https://www.graalv
     }
     ```
 
-4. Build a native executable with VM monitoring enabled and pass the JSON configuration file to `native-image`:
+4. Build a native executable with the VM inspection enabled and pass the JSON configuration file to `native-image`:
     ```shell
     native-image --enable-monitoring=jmxserver,jmxclient,jvmstat -H:DynamicProxyConfigurationFiles=proxy-config.json SimpleJmx
     ```
@@ -141,5 +141,4 @@ Users can enable the JMX agent in a native executable to monitor a client applic
 ### Related Documentation
 
 - [Enabling and disabling JMX](https://docs.oracle.com/javadb/10.10.1.2/adminguide/radminjmxenabledisable.html)
-- [Create Heap Dumps with VisualVM](create-heap-dump-from-native-executable.md)
-- [Dynamic Proxy](../ReachabilityMetadata.md#reflection)
+- [Create Heap Dumps with VisualVM](create-heap-dump-from-native-executable.md)

docs/reference-manual/native-image/guides/build-java-module-app-aot.md

@@ -9,8 +9,8 @@ permalink: /reference-manual/native-image/guides/build-java-modules-into-native-
 
 GraalVM Native Image supports the [Java Platform Module System](https://www.oracle.com/uk/corporate/features/understanding-java-9-modules.html), introduced in Java 9, which means you can convert a modularized Java application into a native executable. 
 
-The `native-image` tool accepts the module-related arguments such as `--module` (`-m`), `--module-path` (`-p`), `--add-opens`, `--add-exports` (same as for the `java` launcher). 
-When such a module-related argument is used, the `native-image` tool itself is used as a module too.
+The `native-image` tool accepts the module-related options such as `--module` (`-m`), `--module-path` (`-p`), `--add-opens`, `--add-exports` (same as for the `java` launcher). 
+When such a module-related option is used, the `native-image` tool itself is used as a module too.
 
 In addition to supporting `--add-reads` and `--add-modules`, all module related options are considered prior to scanning the module path. 
 This helps prevent class loading errors and allow for better module introspection at runtime.
@@ -48,17 +48,17 @@ Make sure you have installed a GraalVM JDK.
 The easiest way to get started is with [SDKMAN!](https://sdkman.io/jdks#graal).
 For other installation options, visit the [Downloads section](https://www.graalvm.org/downloads/).
 
-1. Download or clone the demos repository and navigate to the directory _native-hello-module/_:
+1. Download or clone the demos repository and navigate to the directory _native-image/build-java-modules/_:
     ```bash
     git clone https://github.com/graalvm/graalvm-demos
     ```
     ```bash
-    cd graalvm-demos/native-hello-module
+    cd graalvm-demos/native-image/build-java-modules
     ```
 
 2. Compile and package the project with Maven:
     ```bash
-    mvn package
+    mvn clean package
     ```
 
 3. Test running it on the GraalVM JDK:

docs/reference-manual/native-image/guides/build-native-executable-from-jar.md

@@ -63,8 +63,11 @@ For other installation options, visit the [Downloads section](https://www.graalv
     ```shell
     jar --create --file App.jar --main-class com.example.App -C build .
     ```
-    It will generate a runnable JAR file, named _App.jar_, in the project root directory: 
-    To view its contents, run the command `jar tf App.jar`.
+    It will generate a runnable JAR file, named _App.jar_, in the project root directory.
+    To view its contents, run the command:
+    ```shell
+    jar tf App.jar
+    ```
 
 4. Create a native executable:
     ```shell
@@ -79,9 +82,10 @@ For other installation options, visit the [Downloads section](https://www.graalv
     ./App
     ```
 
-The default behavior of `native-image` is aligned with the `java` command which means you can pass the `-jar`, `-cp`, `-m`  options to build with Native Image as you would normally do with `java`. For example, `java -jar App.jar someArgument` becomes `native-image -jar App.jar` and `./App someArgument`.
+The default behavior of `native-image` is aligned with the `java` command which means you can pass the `-jar`, `-cp`, `-m`  options to build with Native Image as you would normally do with `java`.
+For example, `java -jar App.jar someArgument` becomes `native-image -jar App.jar` and `./App someArgument`.
 
 ### Related Documentation
 
-* [GraalVM Native Image Quick Start](https://luna.oracle.com/lab/47dafec8-4095-4fba-8313-dad43a64dee4)
-* [Build Java Modules into a Native Executable](build-java-module-app-aot.md)
+* [Hands-on Labs: GraalVM Native Image Quick Start](https://luna.oracle.com/lab/47dafec8-4095-4fba-8313-dad43a64dee4)
+* [Build Java Modules into a Native Executable](build-java-module-app-aot.md)

docs/reference-manual/native-image/guides/build-native-shared-library.md

@@ -7,7 +7,7 @@ permalink: /reference-manual/native-image/guides/build-native-shared-library/
 
 # Build a Native Shared Library
 
-To build a native shared library, pass the command-line argument `--shared` to the `native-image` tool, as follows:
+To build a native shared library, pass the command-line option `--shared` to the `native-image` tool, as follows:
 ```shell
 native-image <class name> --shared
 ```
@@ -26,9 +26,10 @@ native-image --shared -jar <jarfile> -o <libraryname>
 ```
 
 GraalVM makes it easy to use C to call into a native shared library. 
-There are two primary mechanisms for calling a method (function) embedded in a native shared library: the [Native Image C API](../C-API.md) and the [JNI Invocation API](https://docs.oracle.com/en/java/javase/22/docs/specs/jni/invocation.html).
+There are two primary mechanisms for calling a method (function) embedded in a native shared library: the [Native Image C API](../C-API.md) and the [JNI Invocation API](https://docs.oracle.com/en/java/javase/23/docs/specs/jni/invocation.html).
 
-This guide describes how to use the **Native Image C API**. It consists of the following steps:
+This guide describes how to use the **Native Image C API**.
+It consists of the following steps:
 1. Create and compile a Java class library containing at least one entrypoint method.
 2. Use the `native-image` tool to create a shared library from the Java class library.
 3. Create and compile a C application that calls that entrypoint method in the shared library.
@@ -66,15 +67,14 @@ A native shared library can have an unlimited number of entrypoints, for example
 ### Run a Demo
 
 In the following example, you create a small Java class library (containing one class), use `native-image` to create a shared library from the class library, and then create a small C application that uses that shared library.
-The C application takes a String as its argument, passes it to the shared library, and prints environment variables that contain the argument.
+The C application takes a String as an argument, passes it to the shared library, and prints environment variables that contain the argument.
 
 ### Prerequisite 
 Make sure you have installed a GraalVM JDK.
 The easiest way to get started is with [SDKMAN!](https://sdkman.io/jdks#graal).
 For other installation options, visit the [Downloads section](https://www.graalvm.org/downloads/).
 
 1. Save the following Java code to a file named _LibEnvMap.java_:
-
     ```java
     import java.util.Map;
     import org.graalvm.nativeimage.IsolateThread;
@@ -113,14 +113,12 @@ For other installation options, visit the [Downloads section](https://www.graalv
 
     It produces the following artifacts:
     ```
-    --------------------------------------------------
     Produced artifacts:
     /demo/graal_isolate.h (header)
     /demo/graal_isolate_dynamic.h (header)
     /demo/libenvmap.dylib (shared_lib)
     /demo/libenvmap.h (header)
     /demo/libenvmap_dynamic.h (header)
-    ==================================================
     ```
 
     If you work with C or C++, use these header files directly. For other languages, such as Java, use the function declarations in the headers to set up your foreign call bindings. 
@@ -156,9 +154,9 @@ For other installation options, visit the [Downloads section](https://www.graalv
 
 4. Compile _main.c_ using the `clang` compiler available on your system:
     ```shell
-    clang -I ./ -L ./ -l envmap -Wl,-rpath ./ -o main main.c 
+    clang -I ./ -L ./ -l envmap -Wl,-rpath ./ -o main main.c
     ```
-    It creates an executable file _main_.
+    It creates an executable file `main`.
 
 5. Run the C application by passing a string as an argument. For example:
     ```shell