Document system properties always included in a native image

Author: olyagpl

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

@@ -6,6 +6,7 @@ permalink: /reference-manual/native-image/overview/Options/
 redirect_from:
   - /reference-manual/native-image/overview/BuildOptions/
   - /reference-manual/native-image/Options/
+  - /reference-manual/native-image/guides/use-system-properties/
 ---
 
 # Command-line Options
@@ -133,6 +134,39 @@ For example:
 * `-H:Dump= -H:MethodFilter=ClassName.MethodName`: dump the compiler graphs of the `native-image` builder.
 * `-XX:Dump= -XX:MethodFilter=ClassName.MethodName`: dump the compile graphs at runtime.
 
+## System Properties
+
+You can define system properties at image build time using the `-D<system.property>=<value>` option syntax.
+It sets a system property for the `native-image` tool, but the property will not be included in the generated executable.
+However, JDK system properties are included in generated executables and are visible at runtime.
+
+For example:
+* `-D<system.property>=<value>` will only be visible at build time. If this system property is accessed in the native executable, it will return `null`.
+* `-Djava.version=24` will be visible at both build time and in the native executable because the value is copied into the binary by default.
+
+The following system properties are automatically copied into the generated executable:
+
+| Name                          | Description                                                       |
+|-------------------------------|-------------------------------------------------------------------|
+| file.separator                | File separator                                                    |
+| file.encoding                 | Character encoding for the default locale                         |
+| java.version                  | Java Runtime Environment version                                  |
+| java.version.date             | General-availability (GA) date of the release                     |
+| java.class.version            | Java class format version number                                  |
+| java.runtime.version          | Java Runtime Environment version                                  |
+| java.specification.name       | Java Runtime Environment specification name                       |
+| java.specification.vendor     | Java Runtime Environment specification vendor                     |
+| java.specification.version    | Java Virtual Machine specification version                        |
+| java.vm.specification.name    | Java Virtual Machine specification name                           |
+| java.vm.specification.vendor  | Java Virtual Machine implementation vendor                        |
+| java.vm.specification.version | Java Virtual Machine specification version                        |
+| line.separator                | Line separator                                                    |
+| native.encoding               | Specifies the host environment's character encoding               |
+| org.graalvm.nativeimage.kind  | Specifies if the image is built as a shared library or executable |
+| path.separator                | Path separator                                                    |
+| stdout.encoding               | Specifies the encoding for `System.out` and `System.err`          |
+| sun.jnu.encoding              | Specifies encoding when parsing values passed via the commandline |
+
 ## Related Documentation
 
 * [Build Configuration](BuildConfiguration.md#order-of-arguments-evaluation)

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

@@ -102,11 +102,11 @@ native-image HelloWorld --initialize-at-build-time=HelloWorld\$Greeter
 GraalVM Native Image: Generating 'helloworld' (executable)...
 ========================================================================================================================
 Greeter is getting ready!
-[1/7] Initializing...                                                                                    (3.1s @ 0.15GB)
- Version info: 'GraalVM dev Java 11 EE'
- Java version info: '11.0.15+4-jvmci-22.1-b02'
- C compiler: gcc (linux, x86_64, 9.4.0)
- Garbage collector: Serial GC
+[1/8] Initializing...                                                                                    (3.1s @ 0.15GB)
+ Java version: 24+36, vendor version: Oracle GraalVM 24+36.1
+ Graal compiler: optimization level: 2, target machine: armv8.1-a, PGO: ML-inferred
+ C compiler: cc (apple, arm64, 16.0.0)
+ Garbage collector: Serial GC (max heap size: 80% of RAM)
 ...
 Finished generating 'helloworld' in 13.6s.
 ./helloworld 

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

@@ -38,7 +38,6 @@ Here you will learn how to:
 - [Specify Class Initialization Explicitly](specify-class-initialization.md)
 - [Use Gradle to Build a Native Executable from a Java Application](https://graalvm.github.io/native-build-tools/latest/gradle-plugin-quickstart.html)
 - [Use Maven to Build a Native Executable from a Java Application](https://graalvm.github.io/native-build-tools/latest/maven-plugin-quickstart.html)
-- [Use System Properties in a Native Executable](use-system-properties.md)
 
 ## Microservices Frameworks
 

docs/reference-manual/native-image/guides/use-system-properties.md

@@ -3,7 +3,7 @@ layout: ni-docs
 toc_group: how-to-guides
 link_title: Use System Properties
 permalink: /reference-manual/native-image/guides/use-system-properties/
-redirect_from: /reference-manual/native-image/Properties/
+redirect_to: /reference-manual/native-image/overview/Options/
 ---
 
 # Use System Properties in a Native Executable
@@ -17,19 +17,15 @@ public class App {
 }
 ```
 
-If you build a native executable using `native-image -Dfoo=bar App`, the system property `foo` will be available at *executable build time*. 
+If you build a native executable using `native-image -Dfoo=bar App`, the system property `foo` will **only** be available at build time.
 This means it is available to the [code in your application that is run at build time](http://www.graalvm.org/sdk/javadoc/org/graalvm/nativeimage/ImageInfo.html#inImageBuildtimeCode--) (usually static field initializations and static initializers).
-Thus, if you run the resulting executable, it will not contain `foo` in the printed list of properties.
+But if you run the resulting executable, it will not contain `foo` in the printed list of properties.
 
-If, on the other hand, you run the executable with `app -Dfoo=bar`, it will display `foo` in the list of properties because you specified property at *executable run time*.
-
-In other words:
-* Pass `-D<key>=<value>` as an option to `native-image` to control the properties seen at build time.
-* Pass `-D<key>=<value>` as an option to a native executable to control the properties seen at run time.
+If, on the other hand, you run the executable with `app -Dfoo=bar`, it will display `foo` in the list of properties because you specified this property.
 
 ## Read System Properties at Build Time
 
-You can read system properties at build time and incorporate them into the resulting executable file, as shown in the following example.
+You can read system properties at build time and incorporate them into the native executable, as shown in the following example.
 
 ### Prerequisite 
 Make sure you have installed a GraalVM JDK.
@@ -116,5 +112,5 @@ For other installation options, visit the [Downloads section](https://www.graalv
 
 ### Related Documentation
 
-* [Class Initialization in Native Image](../ClassInitialization.md)
+* [Command-line Options: System Properties](../BuildOptions.md#system-properties)
 * [Specify Class Initialization Explicitly](specify-class-initialization.md)