Generate Native Images with GraalVM Enterprise

GraalVM Native Image allows to compile a JVM-based application ahead-of-time under closed-world assumption into an executable image or a shared object (ELF-64 or 64-bit Mach-O), called a native image. Native Image generator 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.

*Warning:** Native Image plugin is available as an Early Adopter technology.

Native Image ahead of time compilation functionality can be added to the GraalVM Enterprise core installation with GraalVM Updater tool by running: gu install native-image. After this step, the native-image executable will become available in the bin directory.

Alternatively, Native Image plugin can be manually downloaded from Oracle Technology Network. You must accept the License Agreement before downloading. Install a JAR file using GraalVM Updater tool as usual:

GraalVM native-image supports JVM-based languages, e.g., Java, Scala, Clojure, Kotlin. The resulting native image can, optionally, execute dynamic languages like 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).

Warning: GraalVM Enterprise support for Python, R and Ruby languages is experimental. Experimental features might never be included in a production version, or might change significantly before being considered production-ready.

For information on the prerequisites and limitations of such ahead-of-time compilation, refer to this page.

GraalVM Enterprise also supports monitoring and generating heap dumps of native image processes. To find out more about generating heap dumps, refer to this step-by-step guide.

To build an image for a class in the current working directory, use:

native-image [options] class [imagename]

To build an image for a jar file, use:

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

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 “:”. 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.

Native Image Options

GraalVM native image building options are divided into four categories: image generation options, macro options, non-standard options and server options.

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, macro and server options. The native-image --version command prints product version and exits.

Important: Non-standard and server options are subject to change through a deprecation cycle.

Options to Native Image Generator

The following options to the native-image generator are currently supported:

Option Description
-cp and –-class-path Search for class files through a separated list of directories, JAR and ZIP archives.
-D<name>=<value> Set a system property for the JVM running the image generator.
-J<flag> Pass <flag> directly to the JVM running the image generator.
-O<level> 0 – no optimizations, 1 – basic optimizations (default).
–-verbose Enable verbose output.
–-allow-incomplete-classpath Allow image building with an incomplete class path: report type, resolution errors at run time when they are accessed the first time, instead of during image building.
–-enable-all-security-services Add all security service classes to the generated image.
-–enable-http Enable http support in the generated image.
–-enable-https Enable https support in the generated image.
–-enable-url-protocols List of comma separated URL protocols to enable.
–-features A comma-separated list of fully qualified feature implementation classes.
–-force-fallback Force building of fallback image.
–-auto-fallback Build stand-alone image if possible.
–-no-fallback Build stand-alone image or report failure.
–-pgo A comma-separated list of files from which to read the data, collected for profile-guided optimization of AOT compiled code (reads from default.iprof if nothing is specified).
–-pgo-instrument Instrument AOT compiled code to collect data for profile-guided, optimization into default.iprof file.
–-report-unsupported-elements-at-runtime Report usage of unsupported methods and fields at run time when they are accessed the first time, instead of an error during image building.
–-shared Build a shared library.
–-static Build statically linked executable (requires static libc and zlib).
-da Disable assertions in the generated image.
-ea Enable assertions in the generated image.
-g Generate debugging information.

Macro Options

Option Description
–-language:nfi Make Truffle Native Function Interface language available.
–-language:regex Make Truffle Regular Expression engine available that exposes regular expression functionality in GraalVM supported languages.
–-language:R Make R available as a language for the image.
–-language:python Make Python available as a language for the image.
–-language:llvm Make LLVM bitcode available for the image.
–-language:js Make JavaScript available as a language for the image.
–language:ruby Make Ruby available as a language for the image.
–-tool:profiler Add profiling support to a GraalVM supported language.
–-tool:chromeinspector Add debugging support to a GraalVM supported language.

Important: The --language:python, --language:ruby and --language:R polyglot macro options become available once the corresponding languages engines are added to the base GraalVM installation with GraalVM Updater tool:

gu install python
gu install ruby
gu install R

Non-standard Options

Option Description
–-expert-options List image build options for experts.
–-expert-options-all List all image build options for experts (use at your own risk).
–-configurations-path A : separated list of directories to be treated as option-configuration directories.
–-debug-attach[=<port>] Attach to debugger during image building (default port is 8000).
–-dry-run Output the command line that would be used for building.
-V<key>=<value> Provide values for placeholders in native-image.properties files.

Server Options

Option Description
–-no-server Do not use server-based image building.
–-server-list List current image-build servers.
–-server-list-details List current image-build servers with more details.
–-server-cleanup Remove stale image-build servers entries.
–-server-shutdown Shut down image-build servers under current session ID.
–-server-shutdown-all Shut down all image-build servers.
–-server-session=<custom-session-name> Use custom session name instead of system provided session ID of the calling process.
–-verbose-server Enable verbose output for image-build server handling.