GraalVM Enterprise Native Image

Native Image is a technology 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, and statically linked native code from JDK. It does not run on the Java VM, but includes necessary components like memory management, thread scheduling and so on 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 JVM.

The Native Image builder or native-image is a utility that processes all the classes of an application and their dependencies, including those from the JDK. It statically analyzes these data to determine which classes and methods are reachable during application execution. Then it ahead-of-time compiles that reachable data to a native executable for a specific operating system and architecture. This entire process is called an image build time to clearly distinguish it from the compilation of Java source code to bytecode.

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

License

Native Image is available as an Early Adopter feature. Early adopter features are considered production-ready, but are subject to ongoing development, testing, and modification. For more information, check the License for Early Adopter Versions of Oracle Master Agreement.

Install Native Image

Native Image is distributed as a separate installable and can be easily added to GraalVM Enterprise with the GraalVM Updater tool:

gu install native-image

Alternatively, you can download the Native Image plugin from Oracle GraalVM Downloads and install it from a local JAR file:

gu -L install native-image-installable.jar

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

Prerequisites

For compilation, native-image depends on the local toolchain. Install glibc-devel, zlib-devel (header files for the C library and zlib) and gcc, using a package manager available on your OS. Some Linux distributions may additionally require libstdc++-static.

On Oracle Linux, use yum package manager:

sudo yum install gcc glibc-devel zlib-devel

On Ubuntu Linux, use apt-get package manager:

sudo apt-get install build-essential libz-dev zlib1g-dev

On other Linux distributions, use dnf package manager:

sudo dnf install gcc glibc-devel zlib-devel libstdc++-static

On macOS, use xcode:

xcode-select --install

Prerequisites for Using Native Image on Windows

To make use of Native Image on Windows, observe the following recommendations. The required Microsoft Visual C++ (MSVC) version depends on the JDK version that GraalVM is based on. For GraalVM distribution based on JDK 8, you will need MSVC 2010 SP1 version. The recommended installation method is using Microsoft Windows SDK 7.1:

  1. Download the SDK file GRMSDKX_EN_DVD.iso for from Microsoft.
  2. Mount the image by opening F:\Setup\SDKSetup.exe directly.

For GraalVM distribution based on JDK 11, you will need MSVC 2017 15.5.5 or later version.

The last prerequisite, common for both GraalVM distribution based on JDK 11 and JDK 8, is the proper Developer Command Prompt for your version of Visual Studio. On Windows the native-image tool only works when it is executed from the x64 Native Tools Command Prompt.

Build a Native Image

A native image can be built as a standalone executable, which is the default, or as a shared library (see Build a Shared Library). For an image to be useful, it needs to have at least one entry point method. For standalone executables, Native Image supports Java main methods with a signature that takes the command line arguments as an array of strings:

public static void main(String[] arg) { /* ... */ }

The executable images can have an arbitrary number of entry points, for example, to implement callbacks or APIs.

To build a native image of a Java class file in the current working directory, use:

native-image [options] class [imagename] [options]

To build a native image of a JAR file, use:

native-image [options] -jar jarfile [imagename] [options]

The native-image command needs to provide the class path for all 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 -jar and provide a JAR file that specifies the main method in its manifest.

As an example, take this small Java program that reverses a String using recursion:

public class Example {

    public static void main(String[] args) {
        String str = "Native Image is awesome";
        String reversed = reverseString(str);
        System.out.println("The reversed string is: " + reversed);
    }

    public static String reverseString(String str) {
        if (str.isEmpty())
            return str;
        return reverseString(str.substring(1)) + str.charAt(0);
    }
}

Compile it and build a native image from the Java class:

javac Example.java
native-image Example

The native image builder ahead-of-time compiles the Example class into a standalone executable, example, in the current working directory. Run the executable:

./example

Another option to the native image builder that might be helpful is --install-exit-handlers. It is not recommended to register the default signal handlers when building a shared library. However, it is desirable to include signal handlers when building a native image for containerized environments, like Docker containers. The --install-exit-handlers option gives you the same signal handlers that a JVM does.

For more complex examples, visit the native image generation or compiling a Java and Kotlin app ahead-of-time pages.

Build a Shared Library

To build a native image as a shared library, pass --shared to the native image builder.

native-image --shared class [imagename] [options]

As mentioned in the previous section, you need to have at least one entry point method for a native image to be useful. For shared libraries, Native Image provides the @CEntryPoint annotation to specify entry point methods that should be exported and callable from C. Entry point methods must be static and may only have non-object parameters and return types – this includes Java primitives, but also Word types (including pointers). One of the parameters of an entry point method has to be of type IsolateThread or Isolate. This parameter provides the current thread’s execution context for the call.

For example:

@CEntryPoint static int add(IsolateThread thread, int a, int b) {
    return a + b;
}

When building a shared library, an additional C header file is generated. This header file contains declarations for the C API, which allows creating isolates and attaching threads from C code, as well as declarations for each entry point in the source code. The generated C declaration for the above example is:

int add(graal_isolatethread_t* thread, int a, int b);

Shared library images, alike executable imagesm, can have an arbitrary number of entry points, for example, to implement callbacks or APIs.

How to Determine What Version of GraalVM a Native 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 the Native Image builder:

native-image -cp hello EmptyHello
[emptyhello:11228]    classlist:     149.59 ms
...

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

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

The expected output should match the following:

com.oracle.svm.core.VM GraalVM <version> Java 11 EE

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

Here is an example output:

com.oracle.svm.core.VM.Target.LibC=com.oracle.svm.core.posix.linux.libc.GLibC
com.oracle.svm.core.VM.Target.Platform=org.graalvm.nativeimage.Platform$LINUX_AMD64
com.oracle.svm.core.VM.Target.StaticLibraries=liblibchelper.a|libnet.a|libffi.a|libextnet.a|libnio.a|libjava.a|libfdlibm.a|libzip.a|libjvm.a
com.oracle.svm.core.VM=GraalVM <version> Java 11
com.oracle.svm.core.VM.Target.Libraries=pthread|dl|z|rt
com.oracle.svm.core.VM.Target.CCompiler=gcc|redhat|x86_64|10.2.1

If the image was build with Oracle GraalVM Enterprise Edition the output would instead contain:

com.oracle.svm.core.VM=GraalVM <version> Java 11 EE

Ahead-of-time 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. Continue reading to the GraalVM Native Image Compatibility and Optimization Guide.