- Native Image
- Build Configuration
- Native Image Compatibility and Optimization Guide
- Class Initialization in Native Image
- Static Native Images
- Native Image Options
- Native Image Hosted and Runtime Options
- Native Image C API
- Implementing Native Methods in Java with Native Image
- LLVM Backend for Native Image
- Debug Info Feature
- Points-to Analysis Reports
- Using System Properties in Native Images
- Profile-Guided Optimizations
- Memory Management at Image Run Time
- Generating Heap Dumps from Native Images
- Native Image Maven Plugin
- JCA Security Services on Native Image
- Dynamic Proxy on Native Image
- Java Native Interface (JNI) on Native Image
- Reflection on Native Image
- Accessing Resources in Native Images
- Logging on Native Image
- URL Protocols on Native Image
- Compiler
- GraalVM Updater
- Embedding Reference
- Polyglot Programming
- JVM Languages Reference
- JavaScript and Node.js Reference
- LLVM Languages Reference
- Python Reference
- Ruby Reference
- R Reference Manual
- WebAssembly Reference
Native Image Maven Plugin
To simplify the generation of native images, Native Image now works out of Maven with the Native Image Maven Plugin.
You can build a native executable directly with Maven using the mvn package
command without running the native-image
command as a separate step.
However, the Maven project that uses the plugin should be built on a JDK containing the native-image
tool in <java.home>/lib/svm/bin/native-image
(or <java.home>/jre/lib/svm/bin/native-image
for a Java 8 JDK).
GraalVM is such a JDK (if native-image
has been previously installed with gu
).
Next, add native-image-maven-plugin
into the <plugins>
section of the pom.xml
file:
<plugin>
<groupId>org.graalvm.nativeimage</groupId>
<artifactId>native-image-maven-plugin</artifactId>
<version>${graalvm.version}</version>
<executions>
<execution>
<goals>
<goal>native-image</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
<configuration>
<skip>false</skip>
<imageName>example</imageName>
<buildArgs>
--no-fallback
</buildArgs>
</configuration>
</plugin>
Last, add the org.graalvm.sdk
library dependency in the <dependencies>
list:
<dependency>
<groupId>org.graalvm.sdk</groupId>
<artifactId>graal-sdk</artifactId>
<version>${graalvm.version}</version>
<scope>provided</scope>
</dependency>
The plugin figures out which JAR files it needs to pass to the native image and
what the executable main class should be. If the heuristics fails with the no main manifest attribute, in target/<name>.jar
error, the main class should be
specified in the <configuration>
node of the plugin. When mvn package
completes, an executable is ready for use, generated in the target directory of the project.
Maven Plugin Customization #
If you use Native Image Maven plugin, it will pick up all the configuration for your application stored below the META-INF/native-image/ resource location, as described in Native Image Build Configuration.
It is also possible to customize the plugin within a
<configuration>
node. The following configurations are available.
- Configuration parameter
<mainClass>
: if the execution fails with theno main manifest attribute, in target/<name>.jar
error, the main class should be specified. By default the plugin consults several locations in thepom.xml
file in the following order to determine what the main class of the image should be:<maven-shade-plugin> <transformers> <transformer> <mainClass>
<maven-assembly-plugin> <archive> <manifest> <mainClass>
<maven-jar-plugin> <archive> <manifest> <mainClass>
- Configuration parameter
<imageName>
: if an image filename is not set explicitly, use parameter<imageName>
to provide a custom filename for the image. - Configuration parameter
<buildArgs>
: if you want to pass additional options for to the native image builder, use the<buildArgs>
parameter in the definition of the plugin. For example, to build a native image with assertions enabled that uses com.test.classname as a main class, add:
<configuration>
<imageName>executable-name</imageName>
<mainClass>com.test.classname</mainClass>
<buildArgs>
--no-fallback
</buildArgs>
<skip>false</skip>
</configuration>
If you use GraalVM Enterprise as the JAVA_HOME
environment, the plugin builds a native image with Enterprise features enabled, e.g., an executable will automatically be built with compressed references and other optimizations enabled.
Reusing configuration from a parent POM #
The <buildArgs>
element can be combined between parent and children POM. Suppose the following parent POM definition:
<plugin>
<groupId>org.graalvm.nativeimage</groupId>
<artifactId>native-image-maven-plugin</artifactId>
<version>${graalvm.version}</version>
<configuration>
<imageName>${project.artifactId}</imageName>
<mainClass>${exec.mainClass}</mainClass>
<buildArgs>
<buildArg>--no-fallback<buildArg>
</buildArgs>
</configuration>
</plugin>
Children projects have the ability to append <buildArg>
s in the following way:
<plugin>
<groupId>org.graalvm.nativeimage</groupId>
<artifactId>native-image-maven-plugin</artifactId>
<configuration>
<buildArgs combine.children="append">
<buildArg>--verbose</buildArg>
</buildArgs>
</configuration>
</plugin>
In this case, the arguments that will be passed to the native-image
executable will be:
--no-fallback --verbose