GraalVM allows you to compile your programs ahead-of-time into a native executable. The resulting program does not run on the Java HotSpot VM, but uses necessary components like memory management, thread scheduling from a different implementation of a virtual machine, called Substrate VM. Substrate VM is written in Java and compiled into the native executable. The resulting program has faster startup time and lower runtime memory overhead compared to a Java VM.
Currently, native images work mainly for JVM-based languages, e.g., Java, Scala, Kotlin. The resulting image can, optionally, execute dynamic languages like Ruby, R, or Python, but it does not pre-compile their code itself.
To build a native image of your program use the
native-image utility located in the
bin directory of the GraalVM distribution. For compilation
native-image depends on the local toolchain, so please make sure:
zlib-devel (header files for the C library and
gcc are available on your system.
Image Generation Options
native-image command line needs to provide the class path for all classes using the familiar option from the
-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.
Go over the
native-image command line options that may be useful:
native-image [options] classbuilds 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 jarfilebuilds an image for a jar file.
You may provide additional options to native-image building:
--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;
--sharedbuilds shared library;
-D<name>=<value>sets a system propertys
-J<flag> passes <flag>directly to the JVM running the image generator;
-genables debug info generation;
-O<level>0 - no optimizations, 1 - basic optimizations (default);
-eaenables assertions in the generated image;
--verboseenables verbose output;
--versionprints product version and exits;
--helpprints the help message;
--help-extraprints the help message on non-standard options;
--report-unsupported-elements-at-runtimereports usage of unsupported methods and fields at run time when they are accessed the first time, instead of as an error during image building.
Macro-options are mainly helpful for polyglot capabilities of native images:
--language:pythonto make sure Python is available as a language for the image;
--language:llvmto make sure LLVM bitcode is available for the image;
--language:rubyto make sure Ruby is available as a language for the image;
--tool:chromeinspectoradds truffle debugging support to a truffle-language image;
--tool:profileradds truffle profiling support to a truffle-language image.
Get acquainted with the non-standard native-image building options, that are subject to change without notice:
--no-servertells to not use image-build server;
--server-listlists current image-build servers;
--server-list-detailslists current image-build servers with more details;
--server-cleanupremoves stale image-build servers entries;
--server-shutdownshutdowns image-build servers under current session ID;
--server-shutdown-allshutdown all image-build servers;
--server-session=<custom-session-name>uses custom session name instead of system provided session ID of the calling process;
--debug-attach[=<port>]attaches to debugger during image building (default port is 8000);
--dry-runoutputs the command line that would be used for image building;
--expert-optionslists image build options for experts;
--expert-options-alllists 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.
If the environment variable
NATIVE_IMAGE_CONFIG_FILE is set to a Java properties file,
native-image will use the defaults defined in there on each invocation.
Here is an example of configuration file (saved as
NativeImageArgs = --no-server \ --configurations-path /home/user/custom-image-configs
If the user has this configuration file and export
every time the native-image gets used, it will implicitly use the arguments
NativeImageArgs, plus the arguments specified on command line.
For a more comprehensive list of options please check the documentation on Github.
Generating Heap Dumps
GraalVM also supports monitoring and generating heap dumps of the native image processes using the Monitoring Agent tool. This functionality is available in the Enterprise edition of GraalVM. It is not available in the Community edition of GraalVM.
To find out more about generating heap dumps of the native image processes, refer to the step-by-step documentation.
Limitations of AOT Compilation
To achieve such aggressive ahead-of-time optimizations, we run an aggressive static analysis that requires a closed-world assumption. We need to know all classes and all bytecodes that are reachable at run time. Therefore, it is not possible to load new classes that have not been available during ahead-of-time-compilation.
For a more detailed description of which features of Java are not supported by the native images or supported partially please refer to the documentation on the GitHub. And if you’re interested in learning about the support for Java reflection, there’s a special document for Java reflection support.
Operational information for native images
When does it make sense to run native images instead of the JVM?
- When startup time and memory footprint is important.
- When you want to embed Java code with existing C/C++ applications
What’s the typical performance profile on the SVM?
- Right now peak performance is a bit worse than HotSpot, but we don’t want to advertise that (and we want to fix it of course).
What tools work with SVM: 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 (gdb) and profilers (VTune).