GraalVM Native Image

GraalVM Native Image allows you to ahead-of-time compile Java code to a standalone executable, called a native image. This executable includes the application classes, classes from its dependencies, runtime library classes from JDK and statically linked native code from JDK. It does not run on the Java VM, but includes necessary components like memory management and thread scheduling from a different virtual machine, called “Substrate VM”. Substrate VM is the name for the runtime components (like the deoptimizer, garbage collector, thread scheduling etc.). The resulting program has faster startup time and lower runtime memory overhead compared to a Java VM.

Native Image Generator or native-image is a utility that processes all the classes of your application and their dependencies, including those from the JDK. It statically analyses these classes to determine which classes and methods are reachable and used during application execution. Then it passes all this reachable code as the input to the GraalVM compiler which ahead-of-time compiles it to the native binary.

GraalVM native-image supports JVM-based languages, e.g., Java, Scala, Clojure, Kotlin. The resulting native image can, optionally, execute dynamic languages like JavaScript, Ruby, R, or Python, but it does not pre-compile their code itself. Polyglot embeddings can also be compiled ahead-of-time. To inform native-image of guest languages used by an application, specify --language:<languageId> for each guest language used (e.g., --language:js).

Note: GraalVM Native Image is available as an Early Adopter technology.

Install Native Image

Starting from GraalVM 19.0, Native Image was extracted from the base distribution. This functionality can be added to the core installation with GraalVM Updater utility in a similar way as other additional components.

For GraalVM Enterprise Edition users, download the Native Image component JAR file from Oracle Technology Network and install it by running gu -L install component.jar, where -L option, equivalent to --local-file or --file, tells to install a component from a downloaded archive.

For GraalVM Community Edition users, install a component from the GitHub catalog by its name gu install native-image.

After this additional step, the native-image executable will become available in the bin directory, as for the previous releases.

Take a look at the native image generation or compiling a Java and Kotlin app ahead-of-time samples.

Prerequisites

For compilation native-image depends on the local toolchain, so please make sure: glibc-devel, zlib-devel (header files for the C library and zlib) and gcc are available on your system.

Another prerequisite to consider is the maximum heap size. Physical memory for running a JVM-based application may be insufficient to build a native image. For server-based image building we allow to use 80% of the reported physical RAM for all servers together, but never more than 14GB per server (for exact details please consult the native-image source code). If you run with --no-server option, you will get the whole 80% of what is reported as physical RAM as the baseline. This mode respects -Xmx arguments additionally.

Image Generation Options

The native-image command line needs to provide the class path for all classes using the familiar option from the java launcher: -cp is followed by a list of directories or .jar files, separated by :. The name of the class containing the main method is the last argument; or you can use -jar and provide a .jar file that specifies the main method in its manifest. The syntax of the native-image command is:

  • native-image [options] class to build an executable file for a class in the current working directory. Invoking it executes the native-compiled code of that class.

  • native-image [options] -jar jarfile to build an image for a jar file.

There is a command-line help available. Run native-image --help to get commands overview and native-image --help-extra to print help on non-standard options.

You may provide additional options to the native image building:

  • -cp and --class-path <class search path of directories and zip/jar files> help to search for class files through separated list of directories, JAR archives, and ZIP archives

  • -D<name>=<value> sets a system property for the JVM running the image generator

  • -J<flag> passes <flag> directly to the JVM running the image generator

  • -O<level> 0 – no optimizations, 1 – basic optimizations (default)

  • -ea and -da enables or disables assertions in the generated image

  • --allow-incomplete-classpath allows image building with an incomplete class path and reports type resolution errors at run time when they are accessed the first time, instead of during image building

  • --auto-fallback builds a stand-alone image if possible, which is a default setting, --no-fallback builds a stand-alone image or reports a failure, and --force-fallback forces building of a fallback image

  • --enable-all-security-services adds all security service classes to the generated image

  • --enable-http or --enable-https enables http or https support in the generated image

  • --enable-url-protocols provides a list of comma separated URL protocols to enable

  • --features=<fqcn> provides a comma-separated list of fully qualified feature implementation classes

  • --initialize-at-build-time=<comma separated list of class/package names> initializes classes and implicitly all of their superclasses during image building

  • --initialize-at-run-time=<comma separated list of class/package names> initializes classes and implicitly all of their superclasses at run time and not during image building

  • --report-unsupported-elements-at-runtime reports usage of unsupported methods and fields at run time when they are accessed the first time, instead of as an error during image building;

  • --shared builds a shared library

  • --static builds a statically linked executable. This option prevents linking against shared libraries. This requires the static libc and libstdc++ libraries to be available on the host system. Note: On systems other than Linux, this option has no effect

  • --verbose makes image building output more verbose

  • -g enables the debugging info generation. Note: The option is available only with GraalVM Enterprise Edition

Macro Options

Macro-options are mainly helpful for polyglot capabilities of native images:

  • --language:nfi to make Truffle Native Function Interface language available

  • --language:regex to make Truffle Regular Expression engine available that exposes regular expression functionality in GraalVM supported languages

  • --language:js to make sure JavaScript is available as a language for the image

  • --language:llvm to make sure LLVM bitcode is available for the image

  • --language:python to make sure Python is available as a language for the image

  • --language:ruby to make sure Ruby is available as a language for the image

  • --language:R to make sure R is available as a language for the image

  • --tool:chromeinspector adds debugging support to a Truffle framework based language image

  • --tool:profiler adds profiling support to a Truffle framework based language image

Please note, the --language:python, --language:ruby and --language:R polyglot macro options become available once the corresponding languages engines are installed to the base GraalVM distribution.

Non-standard Options

Get acquainted with the non-standard native image building options, that are subject to change through a deprecation cycle:

  • --no-server tells to not use server-based image building

  • --server-list lists current image-build servers

  • --server-list-details lists current image-build servers with more details

  • --server-cleanup removes stale image-build servers entries

  • --server-shutdown shuts down image-build servers under current session ID

  • --server-shutdown-all shuts down all image-build servers

  • --server-session=<custom-session-name> uses custom session name instead of system provided session ID of the calling process

  • --verbose-server enables verbose output for image-build server handling

Server-side Options

  • --debug-attach[=<port>] attaches to debugger during image building (default port is 8000)

  • --dry-run outputs the command line that would be used for image building

  • --expert-options lists image build options for experts

  • --expert-options-all lists all image build options for experts (to be used at your own risk)

  • --configurations-path <search path of option-configuration directories> a separated list of directories to be treated as option-configuration directories

  • -V<key>=<value> provides values for placeholders in native-image.properties files

For a more comprehensive list of options please check the documentation on Github.

Native Image Configuration

The native-image tool supports a wide range of options to configure a native image build process.

A recommended way to provide configuration is to embed a native-image.properties file into a project jar file. The Native Image tool will automatically pick up all configuration options provided anywhere below the resource location META-INF/native-image/ and use it to construct native-image command line arguments.

To avoid a situation when constituent parts of a non-trivial project are built with overlapping configurations, we recommend to use “subdirectories” within META-INF/native-image. That way a jar file built from multiple maven projects cannot suffer from overlapping native-image configurations. For example:

  • foo.jar has its configurations in META-INF/native-image/foo_groupID/foo_artifactID
  • bar.jar has its configurations in META-INF/native-image/bar_groupID/bar_artifactID

A jar file that contains foo and bar will then contain both configurations without conflicting with one another. Therefore the recommended layout for storing native-image configuration data in jar files is the following:

META-INF/
└── native-image
    └── groupID
        └── artifactID
            └── native-image.properties

Note that the use of ${.} in a native-image.properties file expands to the resource location that contains that exact configuration file. This can be useful if the native-image.properties file wants to refer to resources within its “subfolder”, for example, -H:SubstitutionResources=${.}/substitutions.json.

By having such a composable native-image.properties file, building an image does not require any additional arguments specified on command line. It is sufficient to just run the following command:

$JAVA_HOME/bin/native-image -jar target/<name>.jar

To debug which configuration data gets applied for the image building use native-image --verbose. This will show from where native-image picks up the configurations to construct the final composite configuration command line options for the image builder.

$ native-image --verbose -jar build/basic-app-0.1-all.jar
Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/common/native-image.properties
Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/buffer/native-image.properties
Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/transport/native-image.properties
Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/handler/native-image.properties
Apply jar:file://~/build/basic-app-0.1-all.jar!/META-INF/native-image/io.netty/codec-http/native-image.properties
...
Executing [
    <composite configuration command line options for the image builder>
]

Typical examples of META-INF/native-image based native image configuration can be found in Native Image configuration examples.

Properties File Format

A native-image.properties file is a regular Java properties file that can be used to specify native image configurations. The following properties are supported.

Args

Use this property if your project requires custom native-image command line options to build correctly. For example, the native-image-configure-examples/configure-at-runtime-example has Args = --initialize-at-build-time=com.fasterxml.jackson.annotation.JsonProperty$Access in its native-image.properties file to ensure the class com.fasterxml.jackson.annotation.JsonProperty$Access gets initialized at image built time.

JavaArgs

Sometimes it can be necessary to provide custom options to the JVM that runs the image builder. The JavaArgs property can used in this case.

ImageName

This property can be used to specify a user-defined name for the image. If ImageName is not used, a name gets automatically chosen:

  • native-image -jar <name.jar> has a default image name <name>
  • native-image -cp ... fully.qualified.MainClass has a default image name fully.qualified.mainclass

Note that using ImageName does not prevent the user to override the name later via command line. For example, if foo.bar contains ImageName=foo_app,

  • native-image -jar foo.bar generates the image foo_app but
  • native-image -jar foo.bar application generates the image application.

Order of Arguments Evaluation

The arguments passed to native-image are evaluated left-to-right. This also extends to arguments that get passed indirectly via META-INF/native-image based native-image configuration. Suppose you have a jar file that contains native-image.properties with Args = -H:Optimize=0. Then by using the -H:Optimize=2 option after -cp <jar-file> you can override the setting that comes from the jar file.

Specifying Default Options for Native Image

If there is a need to pass some options for every image build unconditionally, for example, to always generate an image in verbose mode (--verbose), we can make use of the NATIVE_IMAGE_CONFIG_FILE environment variable. If it is set to a Java properties file, the Native Image builder will use the default setting defined in there on each invocation. We have to write a configuration file and export NATIVE_IMAGE_CONFIG_FILE=$HOME/.native-image/default.properties in ~/.bash_profile. Every time native-image gets used, it will implicitly use the arguments specified as NativeImageArgs, plus the arguments specified on the command line. Here is an example of a configuration file, saved as ~/.native-image/default.properties:

NativeImageArgs = --configurations-path /home/user/custom-image-configs \
                  -O1

Runtime vs Build Time Initialization

Building your application into a native image allows you to decide which parts of your application should be run at image build time and which parts have to run at image runtime.

Since GraalVM 19.0 all class-initialization code (static initializers and static field initialization) of the application you build an image for will be executed at image runtime by default. Sometimes it is beneficial to allow class initialization code to get executed at image build time for faster startup (e.g. if some static fields get initialized to runtime independent data). This can be controlled with the following native-image options:

  • --initialize-at-build-time=<comma-separated list of packages and classes>
  • --initialize-at-run-time=<comma-separated list of packages and classes>

In addition to that we allow arbitrary computations at built time that can be put into ImageSingletons that are accessible at image runtime. For more information please have a look at Native Image configuration examples.

To learn more on the topic, continue reading on Application Initialization at Build Time.

Integration with Maven

To simplify the generation of native images, GraalVM Native Image now works out of Maven with the Native Image Maven Plugin.

As demonstrated in the Native Image configuration examples, one can build a native image directly with Maven using the mvn package command without running the native-image tool as a separate step. It is sufficient to add native-image-maven-plugin into the <plugins> section of the pom.xml file:

<plugin>
    <groupId>org.graalvm.nativeimage</groupId>
    <artifactId>native-image-maven-plugin</artifactId>
    <version>${graalvm.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>native-image</goal>
            </goals>
            <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <skip>false</skip>
        <imageName>example</imageName>
        <buildArgs>
            --no-fallback
        </buildArgs>
    </configuration>
</plugin>

and the org.graalvm.sdk library dependency in the <dependencies> list:

<dependency>
    <groupId>org.graalvm.sdk</groupId>
    <artifactId>graal-sdk</artifactId>
    <version>${graalvm.version}</version>
    <scope>provided</scope>
</dependency>

The plugin figures out what jar files it needs to pass to the native image and what the executable main class should be. If the heuristics fails with the no main manifest attribute, in target/<name>.jar error, the main class should be specified in the <configuration> node of the plugin (see Plugin Customization section). When mvn package completes, an executable, generated in the target directory of the project, is ready for use.

Note: As of the GraalVM version 19.3, the Maven <groupId> for the GraalVM Native Image related artifacts, including the plugin, changes from com.oracle.substratevm to org.graalvm.nativeimage (<groupId>org.graalvm.nativeimage</groupId>).

Plugin Customization

When using GraalVM Enterprise Edition as the JAVA_HOME environment, the plugin builds a native image with enterprise features enabled, e.g., an executable will automatically be built with compressed references and other optimizations enabled.

It is also possible to customize native-image-maven-plugin within a <configuration> node. The following configurations are available.

  1. Configuration parameter <mainClass>. If the execution fails with the no main manifest attribute, in target/<name>.jar error, the main class should be specified. By default the plugin consults several locations in the pom.xml file in the following order to determine what the main class of the image should be:
    • <maven-shade-plugin> <transformers> <transformer> <mainClass>
    • <maven-assembly-plugin> <archive> <manifest> <mainClass>
    • <maven-jar-plugin> <archive> <manifest> <mainClass>
  2. Configuration parameter <imageName>. If an image filename is not set explicitly, use parameter <imageName> to provide a custom filename for the image.
  3. Configuration parameter <buildArgs>. If you want to pass additional options for the image building, use the <buildArgs> parameter the definition of the plugin. For example, to build a native image with assertions enabled that uses com.test.classname as a main class, add:
<configuration>
    <imageName>executable-name</imageName>
    <mainClass>com.test.classname</mainClass>
    <buildArgs>
        --no-fallback
    </buildArgs>
    <skip>false</skip>
</configuration>

Memory Management Configuration

When running a native image you can specify: -Xmn - to set the size of the young generation (the amount of memory that can be allocated without triggering a GC). The value is specified in bytes, suffix k, m, or g can be used for scaling for example: -Xmn16M, default 256M. -Xmx - maximum heap size in bytes. Note that this is not the maximum amount of consumed memory, because during GC the system can request more temporary memory, for example -Xmx16M, default unlimited. -Xms - minimum heap size in bytes. The value is specified in bytes, suffix k, m, or g can be used for scaling. Heap space that is unused will be retained for future heap usage, rather than being returned to the operating system.

-XX:+PrintGC: prints some information about garbage collections. -XX:+VerboseGC: prints detailed information about garbage collections.

Low Latency Garbage Collection

When using GraalVM Enterprise you can enable the experimental option to use a lower latency garbage collection implementation. A lower latency GC should improve the performance of the native image applications by reducing the stop-the-world pauses.

To enable it use the -H:+UseLowLatencyGC option when building a native image.

Currently the lower latency GC works on Linux in the AMD64 builds. There are also a few limitations to which configurations it supports:

  • Weak and other special references are currently not supported. All references are treated as strong references instead.
  • Just-in-time (JIT) compiled code is not supported yet.
  • Setting the runtime heap size via -Xms/-Xmx/-Xmn is currently not supported. It is however possible to specify values for those options at image build time, e.g.: -R:MinHeapSize=256m -R:MaxHeapSize=2g -R:MaxNewSize=128m.

You can use -XX:+PrintGC, -XX:+VerboseGC to get some information about garbage collections.

How to Determine What Version of GraalVM an Image Is Generated With?

Assuming you have a Java class file EmptyHello.class containing an empty main method and have generated an empty shared object emptyhello with GraalVM Native Image Generator utility of it:

$ native-image -cp hello EmptyHello
Build on Server(pid: 11228, port: 41223)
[emptyhello:11228]    classlist:     149.59 ms
...

If you do not know what GraalVM distribution is set to the PATH environment variable, how to determine if a native image was compiled with Community or Enterprise Edition? Run this command:

$ strings emptyhello | grep com.oracle.svm.core.VM

The expected output should match the following:

com.oracle.svm.core.VM GraalVM 20.0.0 CE

Note: Python source code or LLVM bitcode interpreted or compiled with GraalVM Community Edition will not have the same security characteristics as the same code interpreted or compiled using GraalVM Enterprise Edition. There is a GraalVM string embedded in each image that allows to figure out the version and variant of the base (Community or Enterprise) used to build an image. The following command will query that information from an image:

strings <path to native-image exe or shared object> | grep com.oracle.svm.core.VM

Profile-guided Optimizations

For additional performance gain and higher throughput in GraalVM ahead-of-time (AOT) mode, make use of profile-guided optimizations (PGO). With PGO, you can collect the profiling data in advance and then feed it to the GraalVM native-image utility, which will use this information to optimize the performance of the resulting binary.

Note: Profile-guided optimizations (PGO) is a GraalVM Enterprise feature.

In GraalVM versions prior to 19.2.0, a commonly used technique to mitigate the missing just-in-time (JIT) optimization is to gather the execution profiles at one run and then use them to optimize subsequent compilation(s). In other words, one needs to create a native image with the --pgo-instrument option to collect the profile information. The --pgo-instrument builds an instrumented native image with profile-guided optimization data collected of AOT compiled code in the default.iprof file, if nothing else is specified. Then you run an example program, saving the result in default.iprof. Finally, you create a second native image with --pgo profile.iprof flag that should be significantly faster.

Starting from 19.2.0, you can collect profiles while running your application in JIT mode and then use this information to generate a highly-optimized native binary. This maximizes the performance even more.

  1. Run a java program in JIT mode with a -Dgraal.PGOInstrument flag to gather the profiling information:
    $ java -Dgraal.PGOInstrument=myclass.iprof MyClass
    
  2. Use the collected data to generate a native image:
    $ native-image --pgo=myclass.iprof MyClass
    
  3. Run the resulting binary:
    $ ./myclass
    

AOT Compilation Limitations

There is a small portion of Java features are not susceptible to ahead-of-time compilation, and will therefore miss out on the performance advantages. To be able to build a highly optimized native executable, we run an aggressive static analysis that requires a closed-world assumption, which means that all classes and all bytecodes that are reachable at runtime must be known at build time. Therefore, it is not possible to load new data that have not been available during ahead-of-time compilation. A more comprehensive list of restrictions can be found in the Native Image Java Limitations document.

Tracing Agent

To overcome some restrictions of GraalVM Native Image and to simplify the configuration process, we implemented a tracing agent which records the behavior of a Java application running on GraalVM or any other compatible JVM that supports Java VM Tool Interface (JVMTI). The tracing agent is supported in both GraalVM Enterprise and Community Editions.

Note: The tracing agent is part of the GraalVM Native Image component, which must be installed first.

The tracing agent helps to deal with such features as Reflection, Java Native Interface, Class Path Resources, and Dynamic Proxy in the GraalVM environment. It is applicable when the static analysis cannot automatically determine what to put into a native image and undetected usages of these dynamic features need to be provided to the generation process in the form of configuration files. The tracing agent observes the application behavior and builds configuration files when running on the Java HotSpot VM, thus it can be enabled on the command line with the java command:

$JAVA_HOME/bin/java -agentlib:native-image-agent=config-output-dir=/path/to/config-dir/ ...

Please note that -agentlib must be specified before a -jar option or a class name or any application parameters in the java command line.

During execution, the agent interfaces with the JVM to intercept all calls that look up classes, methods, fields, resources or request proxy accesses. The agent then generates the jni-config.json, reflect-config.json, proxy-config.json and resource-config.json in the specified output directory. The generated files are stand-alone configuration files in JSON format which contain all intercepted dynamic accesses.

The generated configuration files can later be supplied to the native-image tool by placing them in a META-INF/native-image/ directory on the class path, for example, in a JAR file. Not all of those files must be present. When multiple files with the same name are found, all of them are included.

Read more about advanced usage of the tracing agent in Assisted Configuration of Native Image Builds document.

Java Reflection Support

Further below we will focus on GraalVM Native Image support of Java Reflection API.

Java Reflection provides the ability to inspect and modify applications runtime behavior. It allows to inspect a class or an interface, get its methods and fields information, invoke a method, and even create an object of a class at runtime. The Reflection API classes are part of the java.lang.reflect package.

For GraalVM Native Image to handle the Reflection API, in some cases, a reflection configuration has to be provided at image build time. Within a closed-world assumption approach, an aggressive static analysis can see most classes, methods and fields with certainty because they are used directly. However, when the code accesses program elements by name via reflection, the analysis cannot always determine ahead-of-time what program elements it refers to, and the user’s assistance is then needed to make these elements accessible at runtime. For example, the analysis can discover all dynamic usages of the Class.forName("java.lang.String").getMethod("hashCode").invoke("Hello!"); sequence because only constants are used, but in String.class.getMethod("hashCode".replace('K', 'C')).invoke("Hello!"); it cannot. Where the static analysis fails to access the program elements reflectively, they must be specified in a configuration file via the option -H:ReflectionConfigurationFiles=. For more details, read our documentation on reflection support.

In the given case, the tracing agent can simplify the configuration process and write a reflection configuration file by tracing all reflective lookup operations on the Java HotSpot VM. The traced operations are Class.forName, Class.getMethod, and Class.getField.

For demonstration purposes, save the following code as ReflectionExample.java file:

import java.lang.reflect.Method;

class StringReverser {
    static String reverse(String input) {
        return new StringBuilder(input).reverse().toString();
    }
}

class StringCapitalizer {
    static String capitalize(String input) {
        return input.toUpperCase();
    }
}

public class ReflectionExample {
    public static void main(String[] args) throws ReflectiveOperationException {
        String className = args[0];
        String methodName = args[1];
        String input = args[2];

        Class<?> clazz = Class.forName(className);
        Method method = clazz.getDeclaredMethod(methodName, String.class);
        Object result = method.invoke(null, input);
        System.out.println(result);
    }
}

This is a simple Java program where non-constant strings for accessing program elements by name must come as external inputs. The main method invokes a method of a particular class (Class.forName) whose names are passed as command line arguments. Providing any other class or method name on the command line leads to an exception.

Having compiled the example, invoke each method:

$JAVA_HOME/bin/javac ReflectionExample.java
$JAVA_HOME/bin/java ReflectionExample StringReverser reverse "hello"
olleh
$JAVA_HOME/bin/java ReflectionExample StringCapitalizer capitalize "hello"
HELLO

Now we are going to build a native image as regularly, without a reflection configuration file and run a resulting image:

$JAVA_HOME/bin/native-image ReflectionExample
Build on Server(pid: 59625, port: 58819)
[reflectionexample:59625]    classlist:     467.66 ms
...
Note: Image 'reflectionexample' is a fallback image that requires a JDK for execution (use --no-fallback to suppress fallback image generation).
$ ./reflectionexample

The reflectionexample binary is just a launcher for the Java HotSpot VM, a “fallback image” as stated in the warning message. To generate a native image with reflective lookup operations, we will apply the tracing agent to write a configuration file to be later feed into the native image generation together with a --no-fallback option.

  1. Create a directory META-INF/native-image in the working directory:
    mkdir -p META-INF/native-image
    
  2. Enable the agent and pass necessary command line arguments:
    $JAVA_HOME/bin/java -agentlib:native-image-agent=config-output-dir=META-INF/native-image ReflectionExample StringReverser reverse "hello"
    

    This command creates a reflection-config.json file which makes the StringReverser class and the reverse() method accessible via reflection. The jni-config.json, proxy-config.json ,and resource-config.json configuration files are written in that directory too.

  3. Build a native image:
    $JAVA_HOME/bin/native-image --no-fallback ReflectionExample
    

    The native image generator automatically picks up configuration files in META-INF/native-image directory or subdirectories. However, it is recommended to have META-INF/native-image location on the class path, either via a JAR file or via the -cp flag. It will help to avoid confusion for IDE users where a directory structure is defined by the tool.

  4. Test the methods, but remember that we have not run the tracing agent twice to create a configuration that supports both:
    $ ./reflectionexample StringReverser reverse "hello"
    olleh
    $ ./reflectionexample  StringCapitalizer capitalize "hello"
    Exception in thread "main" java.lang.ClassNotFoundException: StringCapitalizer
     at com.oracle.svm.core.hub.ClassForNameSupport.forName(ClassForNameSupport.java:60)
     at java.lang.Class.forName(DynamicHub.java:1161)
     at ReflectionExample.main(ReflectionExample.java:21)
    

Neither the tracing agent nor native images generator cannot automatically check if the provided configuration files are complete. The agent only observes and records which values are accessed through reflection so that the same accesses are possible in a native image. You can either manually edit the reflection-config.json file, or re-run the tracing agent to transform the existing configuration file, or extend it by using config-merge-dir option:

$JAVA_HOME/bin/java -agentlib:native-image-agent=config-merge-dir=META-INF/native-image ReflectionExample StringCapitalizer capitalize "hello"

Note, the different option config-merge-dir instructs the agent to extend the existing configuration files instead of overwriting them. After re-building the native image, the StringCapitalizer class and the capitalize method will be accessible too.

Generating Heap Dumps

GraalVM also supports monitoring and generating heap dumps of the Native Image processes.

Note: This functionality is available in the Enterprise Edition of GraalVM.

To find out more about generating heap dumps of the native image processes, refer to the step-by-step documentation.

Operational Information for Native Images

How can I specify the default amount of memory a native image can use when it gets executed?

  • To fine-tune maximum memory to be used by an image, set the percent value of physical memory using the -R:MaximumHeapSizePercent=<value> option. For more information, unfold the native-image --expert-options-all list and search for -R:MaximumHeapSizePercent=<value>, -R:MaximumYoungGenerationSizePercent=<value>, -H:AllocationBeforePhysicalMemorySize=<value> and other related options.

When does it make sense to run in a Native Image instead of the JVM?

  • When startup time, memory footprint and packaging size are important.
  • When you want to embed Java code with existing C/C++ applications.

What tools work with Native Image: debugger, profilers? How to use them?

  • The community version does not support DWARF information. The enterprise version supports all native tools that rely on DWARF information, like debuggers (GNU Project Debugger) and profilers (VTune).