Build Native Images with GraalVM Enterprise
The Native Image component of GraalVM 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 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.
*Warning:** Native Image is available as an Early Adopter technology.
Native Image ahead-of-time compilation functionality can be added to the GraalVM Enterprise core installation 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 a JAR file:
- on macOS
gu -L install ./native-image-installable-svm-svmee-<java8/java11>-darwin-amd64-<version>.jar
- on Linux
gu -L install ./native-image-installable-svm-svmee-<java8/java11>-linux-amd64-<version>.jar
-L, equivalent to
--file, tells to treat a local filename of the packaged component as a parameter. After this step, the
native-imageexecutable will become available in the
Alternatively, you can install Native Image component from catalog by running:
gu install native-image
Warning: By installing a component from catalog, GraalVM Enterprise would by default download it from GitHub. To prevent installation of a “community” component version, install it manually.
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.,
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.
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]
native-image command needs to provide the class path for all classes using
the familiar option from the
-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:
|-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.|
|--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: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.|
--language:R polyglot macro options become available once the corresponding languages engines are added to the base GraalVM installation with GraalVM Updater tool.
|--expert-options||List image build options for experts.|
|--expert-options-all||List all image build options for experts (use at your own risk).|
||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.|
|--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.|