Native Image

The Native Image component of GraalVM Enterprise 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.

The input is Java bytecode, compiled from any JVM language. The entire process that produces a native image is image build time to clearly distinguish it from the compilation of Java source code to bytecode. The Native Image builder is a Java application that processes all the classes of an application and its dependencies, dependent JDK libraries and VM components. It statically analyses that data 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 a native executable for a specific operating system and architecture.

To continue reading on ahead-of-time compilation approach, refer to the Application Initialization at Build Time research paper.

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

Install Native Image

Native Image ahead-of-time compilation functionality can be added to GraalVM Enterprise with the GraalVM Updater tool. Download the Native Image component from Oracle Technology Network. You must accept the License Agreement before downloading. Then install Native Image from the JAR file:

Optionally, you can install Native Image from a local components collection:

gu install -C /path/to/downloads/directory native-image

When installing components from a given directory, you can allow installing all components which have a correct version number for GraalVM Enterprise using wildcards:

gu install -C ~/Download/Components/ native*

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

GraalVM native-image supports JVM-based languages, e.g., Java, Scala, 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).

Note: Python, R and Ruby are experimental and not recommended for production use at this time.

Build Native Image

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

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

To build an image for 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 “:”. 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.

For more information, proceed to Native Image Configuration reference. For information on the prerequisites and limitations of the 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.

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.
--version Print component version.
--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.
--auto-fallback Build stand-alone image if possible.
--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.
--initialize-at-build-time A comma-separated list of packages and classes and implicitly all of their superclasses that are initialized during image generation. An empty string designates all packages.
--initialize-at-run-time A comma-separated list of packages and classes and implicitly all of their subclasses that must be initialized at runtime and not during image building. An empty string is not supported.
--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.

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 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.