You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/reference-manual/native-image/README.md
+2-60
Original file line number
Diff line number
Diff line change
@@ -144,67 +144,9 @@ To build a native executable from a JAR file in the current working directory, u
144
144
native-image [options] -jar jarfile [imagename]
145
145
```
146
146
147
-
1. Prepare the application.
147
+
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`.
148
148
149
-
- Create a new Java project named "App", for example in your favorite IDE or from your terminal, with the following structure:
150
-
151
-
```shell
152
-
| src
153
-
| --com/
154
-
| -- example
155
-
| -- App.java
156
-
```
157
-
158
-
- Add the following Java code into the _src/com/example/App.java_ file:
159
-
160
-
```java
161
-
package com.example;
162
-
163
-
public class App {
164
-
165
-
public static void main(String[] args) {
166
-
String str = "Native Image is awesome";
167
-
String reversed = reverseString(str);
168
-
System.out.println("The reversed string is: " + reversed);
This is a small Java application that reverses a String using recursion.
179
-
180
-
2. Compile the application:
181
-
182
-
```shell
183
-
javac -d build src/com/example/App.java
184
-
```
185
-
This produces the file _App.class_ in the _build/com/example_ directory.
186
-
187
-
3. Create a runnable JAR file:
188
-
189
-
```shell
190
-
jar --create --file App.jar --main-class com.example.App -C build .
191
-
```
192
-
It will generate a runnable JAR file, named `App.jar`, in the root directory:
193
-
To view its contents, type`jar tf App.jar`.
194
-
195
-
4. Create a native executable:
196
-
197
-
```
198
-
native-image -jar App.jar
199
-
```
200
-
It will produce a native executable in the project root directory.
201
-
5. Run the native executable:
202
-
203
-
```shell
204
-
./App
205
-
```
206
-
207
-
The `native-image` tool can provide the class path forall classes using the familiar option from the java launcher: `-cp`, followed by a list of directories or JAR files, separated by `:` on Linux and macOS platforms, or `;` on Windows. The name of the class containing the `main` method is the last argument, or you can use the `-jar` option and provide a JAR file that specifies the `main` methodin its manifest.
149
+
[Follow this guide](guides/build-native-executable-from-jar.md) to build a native executable from a JAR file.
You can build a native executable from a class file, from a JAR file, or from a module. This guide demonstrates how to build a native executable from a JAR file.
11
+
12
+
To build a native executable from a JAR file in the current working directory, use the following command:
This is a small Java application that reverses a String using recursion.
49
+
50
+
2. Compile the application:
51
+
52
+
```shell
53
+
javac -d build src/com/example/App.java
54
+
```
55
+
This produces the file _App.class_ in the _build/com/example_ directory.
56
+
57
+
3. Create a runnable JAR file:
58
+
59
+
```shell
60
+
jar --create --file App.jar --main-class com.example.App -C build .
61
+
```
62
+
It will generate a runnable JAR file, named _App.jar_, in the project root directory:
63
+
To view its contents, run the command`jar tf App.jar`.
64
+
65
+
4. Create a native executable:
66
+
67
+
```
68
+
native-image -jar App.jar
69
+
```
70
+
It will produce a native executable in the project root directory.
71
+
5. Run the native executable:
72
+
73
+
```shell
74
+
./App
75
+
```
76
+
77
+
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`.
Reflection is a feature of the Java programming language that enables a running Java program to examine and modify attributes of its classes, interfaces, fields, and methods.
12
+
To build a native executable for a Java application that uses Java reflection, dynamic proxy objects, JNI, or class path resources, you should either provide the `native-image` tool with JSON-formatted configuration files or pre-compute metadata in the code.
11
13
12
-
The `native-image` utility provides partial support for reflection. It uses static analysis to detect the elements of your application that are accessed using the Java Reflection API. However, because the analysis is static, it cannot always completely predict all usages of the API when the program runs. In these cases, you must provide a configuration file to the native-image utility to specify the program elements that use the API.
14
+
You can create configuration file(s) by hand, but a more convenient approach is to generate the configuration using the Tracing agent (from now on, the agent).
15
+
This guide demonstrates how to configure `native-image` with the agent. The agent generates the configuration for you automatically when you run an application on a JVM.
13
16
17
+
To learn how to build a native executable with the metadata pre-computed in the code, [follow this guide](use-reachability-metadata-repository-gradle.md).
18
+
19
+
The example application in this guide uses Java reflection. The `native-image` tool only partially detects application elements that are accessed using the Java Reflection API. So, you need to provide it with details about reflectively accessed classes, methods, and fields.
14
20
## Example with No Configuration
21
+
15
22
The following application demonstrates the use of Java reflection.
16
23
17
24
1. Save the following source code in a file named _ReflectionExample.java_:
@@ -78,16 +85,15 @@ The following application demonstrates the use of Java reflection.
78
85
is used by the application and therefore did not include it in the native executable.
79
86
80
87
## Example with Configuration
81
-
To build a native executable containing references to the classes and methods that are accessed via reflection, provide the `native-image` utility with a configuration file that specifies the classes and corresponding methods. (For more information about configuration files, see [Reflection Use in Native Images](../Reflection.md).) You can create this file by hand, but a more convenient approach is to generate the configuration using the tracing agent. The agent generates the configuration for you automatically when you run your application (for more information, see [Assisted Configuration with Tracing Agent](../AutomaticMetadataCollection.md#tracing-agent).
82
88
83
-
The following steps demonstrate how to use the javaagent tool, and its output, to create a native executable that relies on reflection.
89
+
The following steps demonstrate how to use the agent, and its output, to create a native executable that relies on reflection and requires configuration.
84
90
85
-
1. Create a directory `META-INF/native-image` in the working directory:
91
+
1. Create a directory named _META-INF/native-image_ in the working directory:
86
92
```shell
87
93
mkdir -p META-INF/native-image
88
94
```
89
95
90
-
2. Run the application with the tracing agent enabled, as follows:
96
+
2. Run the application with the agent enabled, as follows:
Copy file name to clipboardexpand all lines: docs/reference-manual/native-image/guides/debug-native-executables-with-gdb.md
+50-3
Original file line number
Diff line number
Diff line change
@@ -28,14 +28,61 @@ This will enable source-level debugging, and the debugger (GDB) then correlates
28
28
Follow the steps to test debugging a native executable with GDB. The below workflow is know to work on Linux OS with GDB 10.1.
29
29
30
30
1. Save the following code to the file named _GDBDemo.java_.
31
+
```java
32
+
publicclassGDBDemo {
33
+
staticlong fieldUsed =1000;
34
+
35
+
publicstaticvoidmain( String[] args ) {
36
+
if (args.length >0) {
37
+
int n =-1;
38
+
try {
39
+
n =Integer.parseInt(args[0]);
40
+
} catch (NumberFormatException ex) {
41
+
System.out.println(args[0] +" is not a number!");
42
+
}
43
+
if (n <0) {
44
+
System.out.println(args[0] +" is negative.");
45
+
}
46
+
double f = factorial(n);
47
+
System.out.println(n +"! = "+ f);
48
+
}
49
+
50
+
if (false)
51
+
neverCalledMethod();
52
+
53
+
StringBuilder text =newStringBuilder();
54
+
text.append("Hello World from GraalVM Native Image and GDB in Java.\n");
55
+
System.out.println(text.toString());
56
+
}
57
+
58
+
staticvoidneverCalledMethod() {
59
+
System.out.println("This method is unreachable and will not be included in the native executable.");
60
+
}
61
+
62
+
staticdoublefactorial(intn) {
63
+
if (n ==0) {
64
+
return1;
65
+
}
66
+
if (n >= fieldUsed) {
67
+
returnDouble.POSITIVE_INFINITY;
68
+
}
69
+
double f =1;
70
+
while (n >1) {
71
+
f *= n--;
72
+
}
73
+
return f;
74
+
}
75
+
}
76
+
77
+
```
31
78
32
79
2.Compile it and generate a native executable with debug information:
33
80
34
81
```shell
35
-
$JAVA_HOME/bin/javac JFRDemo.java
82
+
$JAVA_HOME/bin/javac GDBDemo.java
36
83
```
37
84
```shell
38
-
native-image -g -O0 JFRDemo
85
+
native-image -g -O0GDBDemo
39
86
```
40
87
The `-g` option instructs `native-image` to generate debug information. The resulting native executable will contain debug records in a format GDB understands.
41
88
@@ -44,7 +91,7 @@ Follow the steps to test debugging a native executable with GDB. The below workf
44
91
3.Launch the debugger and run your native executable:
These guides are to help developers get started with GraalVM Native Image, acquaint them with the available features, and describe potential usage scenarios.
11
+
These guides help developers get started with GraalVM Native Image, acquaint them with available features, and describe potential usage scenarios.
Copy file name to clipboardexpand all lines: docs/reference-manual/native-image/guides/optimize-native-executable-with-pgo.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -186,4 +186,4 @@ With PGO you "train" your application for specific workloads and significantly i
186
186
187
187
### Related Documentation
188
188
189
-
- [Improving performance of GraalVM native images with profile-guided optimizations](https://medium.com/graalvm/improving-performance-of-graalvm-native-images-with-profile-guided-optimizations-9c431a834edb)
189
+
- [Optimize Cloud Native Java Apps with GraalVM Enterprise PGO](https://luna.oracle.com/lab/3f0b7c86-6105-4b7a-9a3b-eb73b251a1aa)
# Use Shared Reachability Metadata with Native Image Gradle Plugin
8
+
# Configure Native Image Using Shared Reachability Metadata
9
9
10
10
With the Gradle plugin for GraalVM Native Image you can easily build a native executable from a Java application. The plugin is provided as part of the [Native Build Tools project](https://graalvm.github.io/native-build-tools/latest/index.html) and uses the [Gradle build tool](https://gradle.org/).
11
-
If the application does not load dynamically any classes at run time, then your workflow is just one command: `./gradlew nativeRun`.
11
+
If the application does not dynamically load any classes at run time, then your workflow is just one command: `./gradlew nativeRun`.
12
12
13
-
In the real-world scenario, your application will, most likely, call either Java Reflection, Dynamic Proxy objects, or call some native code, or access classpath resources - the dynamic features which the `native-image` tool must be aware of at build time, and provided in the form of [metadata](../ReachabilityMetadata.md).
13
+
In the real-world, your application will, most likely, call either Java Reflection, Dynamic Proxy objects, or call some native code, or access resources on the class path - dynamic features that the `native-image` tool must be aware of at build time, and provided in the form of [metadata](../ReachabilityMetadata.md).
14
14
Native Image loads classes dynamically at build time, and not at run time.
15
15
16
-
Depending on your application dependencies, there could be three ways to provide the metadata with the Native Image Gradle Plugin:
16
+
Depending on your application dependencies, there are three ways to provide the metadata with the Native Image Gradle Plugin:
17
17
18
18
1.[Using the Tracing Agent](#build-a-native-executable-with-the-agent)
19
19
2.[Using the shared GraalVM Reachability Metadata Repository](#build-a-native-executable-using-the-graalvm-reachability-metadata-repository)
0 commit comments