Maven plugin for GraalVM Native Image building

Introduction

The Maven plugin for GraalVM Native Image building adds support for building and testing native images using Apache Maven™.

For upgrading please take a look at the Changelog.

Quickstart

This plugin first requires that you setup GraalVM and native-image properly. It will then make use of Maven profiles to enable building and testing of native images.

Configuration

Registering the plugin

Add the following profile to your pom.xml file to register the native-maven-plugin.

  <profiles>
    <profile>
      <id>native</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.graalvm.buildtools</groupId>
            <artifactId>native-maven-plugin</artifactId>
            <version>${native.maven.plugin.version}</version>
            <extensions>true</extensions>
            <executions>
              <execution>
                <id>build-native</id>
                <goals>
                  <goal>build</goal>
                </goals>
                <phase>package</phase>
              </execution>
              <execution>
                <id>test-native</id>
                <goals>
                  <goal>test</goal>
                </goals>
                <phase>test</phase>
              </execution>
            </executions>
            <configuration>
              <!-- ... -->
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

You can then build a native executable directly with Maven using the mvn -Pnative -DskipTests package command without running the native-image command as a separate step.

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 fail 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 -Pnative package completes, an executable is ready for use, generated in the target directory of the project.

Testing pre-releases

You can use development versions of the plugin by adding our snapshot repository. Pre-releases are provided for convenience, without any guarantee.

<pluginRepositories>
    <pluginRepository>
        <id>graalvm-native-build-tools-snapshots</id>
        <name>GraalVM native-build-tools Snapshots</name>
        <url>https://raw.githubusercontent.com/graalvm/native-build-tools/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Configuration options

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 configuration options are available.

<mainClass>

If the execution fails with the no main manifest attribute, in target/<name>.jar error, the main class should be specified. By default the plugin consults several locations in the pom.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>

<imageName>

Use <imageName> to set a custom filename for the generated native image. If a custom image name is not supplied, the artifact ID of the project will be used by default.

<buildArgs>

If you want to pass additional arguments to the native image builder, use <buildArgs> in the configuration of the plugin:

<buildArgs>
    <arg>--argument</arg>
</buildArgs>

<skipNativeBuild>: To skip generation of the native image, supply the following in the configuration of the plugin:

<skipNativeBuild>true</skipNativeBuild>

<skipNativeTests>: To skip generation and execution of the native image compiled tests, supply the following in the configuration of the plugin:

<skipNativeTests>true</skipNativeTests>

<debug>: If you want to enable generation of debugging information supply the following in the configuration of the plugin:

<debug>true</debug>

<verbose>: If you want to enable verbose output during native-image building supply the following in the configuration of the plugin:

<verbose>true</verbose>

<sharedLibrary>: If you want to build image as a shared library supply the following in the configuration of the plugin:

<sharedLibrary>true</sharedLibrary>

<useArgFile>: If you want to use argument file for native-image building supply the following in the configuration of the plugin:

<useArgFile>true</useArgFile>

<quickBuild>: If you want to build the image using quick build mode, supply the following in the configuration of the plugin (alternatively set the GRAALVM_QUICK_BUILD environment variable to true):

<quickBuild>true</quickBuild>

<excludeConfig>: In order to exclude configuration from present jar files, specify:

<excludeConfig>
    <entry>
        <jarPath>dummy/path/to/file.jar</jarPath>
        <resourcePattern>*</resourcePattern>
    </entry>
</excludeConfig>

<environment>: To set environment options for native-image building supply the following in the configuration of the plugin:

<environment>
    <variable>value</variable>
</environment>

<systemPropertyVariables>: To specify system properties used for native-image building supply the following in the configuration of the plugin:

<systemPropertyVariables>
    <propertyName>value</propertyName>
</systemPropertyVariables>

<jvmArgs>: To specify JVM arguments used for native-image building supply the following in the configuration of the plugin:

<jvmArgs>
    <arg>argument1</arg>
    <arg>argument2</arg>
</jvmArgs>

<configurationFileDirectories>: If you want to specify custom directories where configuration files should be looked up, supply the following in the configuration of the plugin:

<configurationFileDirectories>
    <dir>path/to/dir</dir>
</configurationFileDirectories>

<classpath>: Sets a custom classpath instead of plugin generated one. Usage:

<classpath>
    <entry>path/to/file.jar</entry>
    <entry>path/to/classes</entry>
</classpath>

<classesDirectory>: If you want to specify custom path to packed JAR, or a custom directory that contains only application classes, but want the plugin to still automatically add classpath entries for dependencies, simply add:

<classesDirectory>
    path/to/dir
</classesDirectory>

<agent>: Configuration of the native agent. See Enabling the agent and Configuring agent options for details.

For example, to build a native image named executable-name that uses org.example.ClassName as its main class with assertions enabled, add the following <configuration> block for the native-maven-plugin.

<configuration>
  <imageName>executable-name</imageName>
  <mainClass>org.example.ClassName</mainClass>
  <fallback>false</fallback>
  <verbose>true</verbose>
</configuration>

Most of the aforementioned properties can also be set from command line as a part of Maven invocation — for example if you want to temporarily enable verbose mode you can append -Dverbose to your Maven invocation.

If you use GraalVM Enterprise as the JAVA_HOME environment, the plugin builds a native image with enterprise features enabled — for example, 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 POMs. Suppose you have the following parent POM definition:

<plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
  <version>${current_plugin_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> arguments in the following way:

<plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-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

Testing support

This plugin supports running tests on the JUnit Platform as native images. This means that tests will be compiled and executed as native code.

In theory, any TestEngine supported on the JUnit Platform should be supported by this plugin as long as the programming language used by the TestEngine and the programming language used to write the tests is supported in a GraalVM native image. This plugin provides explicit support for the JUnit Jupiter and JUnit Vintage test engines, and support for additional test engines should be possible with custom native configuration.

In order to use the recommended JUnit Platform test listener mode, you need to enable extensions for the native-maven-plugin by adding <extensions>true</extensions> as follows.

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>${native.maven.plugin.version}</version>
    <extensions>true</extensions>

Running mvn -Pnative test will then build and run native tests.

Version compatibility

This plugin requires JUnit Platform 1.8 or higher and Maven Surefire 2.22.0 or higher to run tests within a native image.

Each version of the Maven Surefire plugin has a dependency on a particular version of the JUnit Platform. You therefore need to ensure that Maven Surefire is using at least version 1.8 of the JUnit Platform. Beginning with version 3.0 M4, Maven Surefire will automatically align the JUnit Platform version used by Surefire with the version needed by the user’s configured version of JUnit Jupiter or JUnit Vintage. Since the examples in this document use Maven Surefire 3.0 M5, their maven POMs do not require any special configuration regarding the JUnit Platform version. However, if you are using a version of Maven Surefire prior to 3.0 M4 you will need to add an explicit dependency on the junit-platform-launcher artifact to the dependencies section of your native profile configuration as in the following example.

<dependencies>
	<dependency>
		<groupId>org.junit.platform</groupId>
		<artifactId>junit-platform-launcher</artifactId>
		<version>1.8.2</version>
		<scope>test</scope>
	</dependency>
</dependencies>

If you have imported the junit BOM or are using a plugin that manages JUnit versions for you — for example, Spring Boot — you may want to omit the <version> configuration in the above example.

If Maven Surefire is using an older version of the JUnit Platform, the build will fail with an error similar to the following when attempting to run tests in a native image.

[ERROR] Test configuration file wasn't found. Make sure that test execution wasn't skipped.

Disabling testing support

If you wish to disable tests on the JVM as well as tests within a native image, you can invoke Maven with the -DskipTests flag. This flag is supported by Maven Surefire and Native Build Tools. Several examples in Running your application with the agent demonstrate the use of this flag.

If you wish to run tests on the JVM with Maven Surefire but skip testing within a native image, you can invoke Maven with the -DskipNativeTests flag. This flag is specific to Native Build Tools. For example, you might wish to disable only native testing support for use cases such as the following:

You don’t actually want to run your tests in native mode.
Your library or application uses a testing framework that is not supported on the JUnit Platform.
You need to use the agent when running tests on the JVM but do not wish to run those same tests in native mode.

Long classpath, @argument file and shading support

Under Windows, it is possible that the length of the classpath exceeds what the operating system supports when invoking the CLI to build a native image.

To avoid this, since release 0.9.10, the plugin will use an argument file to pass the arguments to the native-image tool, instead of passing them directly.

In case you are using a GraalVM version older than 21.3, you will however have to use a workaround, since the argument file wasn’t supported.

One option is to use a shaded jar and use it instead of individual jars on classpath.

First, you’ll need to setup the Maven Shade plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <shadedArtifactAttached>true</shadedArtifactAttached>
            </configuration>
        </execution>
    </executions>
</plugin>

If you need testing support, add the JUnit Platform Native dependency explicitly:

<dependencies>
    <dependency>
        <groupId>org.graalvm.buildtools</groupId>
        <artifactId>junit-platform-native</artifactId>
        <version>${junit.platform.native.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Then the native plugin needs to be configured to use this jar instead of the full classpath:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>${native.maven.plugin.version}</version>
    <extensions>true</extensions>
    <executions>
        <execution>
            <id>build-native</id>
            <goals>
                <goal>build</goal>
            </goals>
            <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <skip>false</skip>
        <useArgFile>false</useArgFile>
        <imageName>${imageName}</imageName>
        <fallback>false</fallback>
        <classpath>
            <param>${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar</param>
        </classpath>
    </configuration>
</plugin>

Depending on the other plugins your build uses (typically the Spring Boot plugin), you might have to configure, in addition, the main class:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
	<artifactId>native-maven-plugin</artifactId>
	<version>${native.buildtools.version}</version>
	<configuration>
		<imageName>${project.artifactId}</imageName>
		<mainClass>${exec.mainClass}</mainClass>
		<buildArgs>
			<buildArg>--no-fallback</buildArg>
		</buildArgs>
		<classpath>
			<param>
				${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar
			</param>
		</classpath>
...

To be able to execute tests in native mode, you will need more setup:

Create a src/assembly/test-jar-with-dependencies.xml file with the following contents:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
    <id>tests</id>
    <formats>
        <format>jar</format>
    </formats>
    <fileSets>
        <fileSet>
            <directory>${project.build.directory}/test-classes</directory>
            <outputDirectory>/</outputDirectory>
        </fileSet>
        <fileSet>
            <directory>${project.build.outputDirectory}</directory>
            <outputDirectory>/</outputDirectory>
        </fileSet>
    </fileSets>
    <includeBaseDirectory>false</includeBaseDirectory>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <unpack>true</unpack>
            <scope>test</scope>
        </dependencySet>
    </dependencySets>
</assembly>

Add the assembly plugin to your native profile:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>2.4.1</version>
    <configuration>
        <descriptors>
            <descriptor>src/assembly/test-jar-with-dependencies.xml</descriptor>
        </descriptors>
    </configuration>
    <executions>
        <execution>
            <id>make-test-jar</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Due to a limitation in Maven, you will need to move the tests execution to the "integration-test" phase:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.0.0-M5</version>
</plugin>
<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>${native.maven.plugin.version}</version>
    <extensions>true</extensions>
    <executions>
        <execution>
            <id>test-native</id>
            <goals>
                <goal>test</goal>
            </goals>
            <phase>integration-test</phase>
            <configuration>
                <classpath>
                    <param>${project.build.directory}/${project.artifactId}-${project.version}-tests.jar</param>
                </classpath>
            </configuration>
        </execution>
        <execution>
            <id>build-native</id>
            <goals>
                <goal>build</goal>
            </goals>
            <phase>package</phase>
            <configuration>
                <classpath>
                    <param>${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar</param>
                </classpath>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <skip>false</skip>
        <useArgFile>false</useArgFile>
        <imageName>${imageName}</imageName>
        <fallback>false</fallback>
    </configuration>
</plugin>

Finally, you will need to execute tests using the integration-test phase instead of test:

./mvn -Pnative integration-test

Please refer to the Maven Shade plugin documentation for more details on how to configure shading and the Maven Assembly plugin documentation to tweak what to include in tests.

Reflection support and running with the native agent

If your project requires reflection, classpath resources, dynamic proxies or other features requiring explicit native configuration, it may prove helpful to first run your application or tests using the native-image-agent.

The Native Image Maven plugin simplifies generation of the required configuration files by injecting the agent automatically for you (this includes, but is not limited to the reflection file).

The agent generates the native configuration files in a subdirectory of target/native/agent-output. Although those files will be automatically used if you run your build with the agent enabled, you should consider reviewing the generated files and adding them to your sources instead.

Enabling the agent

The agent is disabled by default, but it can be enabled within your pom.xml file or via the command line.

To enable the agent by default, specify <enabled>true</enabled> as follows in the configuration of the native-maven-plugin in your POM.

<configuration>
  <agent>
    <enabled>true</enabled>
  </agent>
</configuration>

To enable the agent via the command line, supply the -Dagent=true flag when running Maven. The examples in the following sections demonstrate how to do this for your application and for tests.

If you have enabled the agent within your POM, you can still disable it via the command line by supplying the -Dagent=false flag.

Configuring agent options

If you would like to configure the options for the agent — for example, to configure experimental features such as experimental-class-loader-support or advanced features such as Caller-based Filters and Access Filters — you can include <options> within the <agent> block of the configuration of the native-maven-plugin in your POM.

You can supply multiple sets of <options>.
You can declare an unnamed <options> element which will always be used whenever the agent is enabled. This should be used to declare common options that will be used for all executions with the agent.
Additional <options> elements must declare a unique name attribute.
- To configure options for your application, use the name main.
- To configure options for your tests, use the name test.
- To configure additional sets of options, declare each with a unique name other than main or test.
The main options are enabled automatically whenever your application is run with the agent.
The test options are enabled automatically whenever your tests are run with the agent.
To enable any other set of named <options>, supply -DagentOptions=<NAME> as a command-line argument for Maven, where <NAME> corresponds to the name attribute of the <options> element.

The Native Image Maven plugin automatically configures the config-output-dir for the agent. An attempt to configure a custom value for the config-output-dir option will therefore result in a build failure.

The following example is likely more complex than anything you would do in your own projects, but it demonstrates how to configure four sets of <options>.

The unnamed set is always active.
The main set is automatically active for application execution.
The test set is automatically active for test execution.
The periodic-config set is never active by default, but it can be enabled via -DagentOptions=periodic-config on the command line.

<configuration>
    <agent>
        <options><!-- shared options -->
            <option>experimental-class-loader-support</option>
        </options>
        <options name="main"><!-- main options -->
            <option>access-filter-file=${basedir}/src/main/resources/access-filter.json</option>
        </options>
        <options name="test"><!-- test options -->
            <option>access-filter-file=${basedir}/src/test/resources/access-filter.json</option>
        </options>
        <options name="periodic-config"><!-- periodic-config options -->
            <option>config-write-period-secs=30</option>
            <option>config-write-initial-delay-secs=5</option>
        </options>
    </agent>
</configuration>

Running tests with the agent

The simplest way to use the agent is to do it via execution of your tests.

Run your test suite with:

mvn -Pnative -Dagent=true test

When the agent system property is set to true (or when the agent is enabled in the POM), the agent will be automatically attached to your Maven Surefire test execution, and the generated files can be found in the target/native/agent-output/test directory.

To run your tests with custom agent options, supply the -DagentOptions=<NAME> command-line argument to Maven as follows. See the documentation for agent options for details.

mvn -Pnative -Dagent=true -DagentOptions=periodic-config test

Running your application with the agent

Executing your application with the agent is more involved and requires you to configure a separate mojo execution which allows forking the Java process.

In your native Maven profile section, add the following:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.0.0</version>
    <executions>
        <execution>
            <id>java-agent</id>
            <goals>
                <goal>exec</goal>
            </goals>
            <configuration>
                <executable>java</executable>
                <workingDirectory>${project.build.directory}</workingDirectory>
                <arguments>
                    <argument>-classpath</argument>
                    <classpath/>
                    <argument>${mainClass}</argument>
                </arguments>
            </configuration>
        </execution>
    </executions>
</plugin>

Then you can execute your application with the agent by running:

mvn -Pnative -Dagent=true -DskipTests -DskipNativeBuild=true package exec:exec@java-agent

To execute your application with custom agent options, supply the -DagentOptions=<NAME> command-line argument to Maven as follows. See the documentation for agent options for details.

mvn -Pnative -Dagent=true -DagentOptions=periodic-config -DskipTests -DskipNativeBuild=true package exec:exec@java-agent

Both of the above commands will generate configuration files in the target/native/agent-output/main directory. If you want to run your native application with those configuration files, you then need to execute the following command:

mvn -Pnative -Dagent=true -DskipTests package exec:exec@native

GraalVM Reachability Metadata Support

Since release 0.9.12, the plugin adds support for the GraalVM reachability metadata repository. This repository provides reachability metadata for libraries that do not support GraalVM Native Image.

Enabling the metadata repository

Support needs to be enabled explicitly by including the following into the <configuration> element:

Enabling the metadata repository

<metadataRepository>
    <enabled>true</enabled>
</metadataRepository>

Alternatively, you can use a remote repository, in which case you can specify the URL of the ZIP file:

Enabling a remote repository

<metadataRepository>
    <enabled>true</enabled>
    <url>${metadata.url}</url>
</metadataRepository>

For debugging purposes you can use a local repository:

Enabling a local repository

<metadataRepository>
    <enabled>true</enabled>
    <localPath>${project.basedir}/config-directory</localPath> (1)
</metadataRepository>

1	The local path can point to an exploded directory, or to a compressed ZIP file.

Configuring the metadata repository

Once activated, for each library included in the native image, the plugin will automatically search for GraalVM reachability metadata in the repository that was released together with the plugin. In case you want to use another verion of the metadata use:

Choosing a version for the metadata repository

<metadataRepository>
    <enabled>true</enabled>
    <version>0.1.0</version>
</metadataRepository>

In some cases, you may need to exclude a particular module from the search. This can be done by configuring that particular dependency:

Excluding a module from search

<metadataRepository>
    <enabled>true</enabled>
    <localPath>${project.basedir}/config-directory</localPath>
    <dependencies>
        <dependency>
            <groupId>org.graalvm.internal</groupId>
            <artifactId>library-with-reflection</artifactId>
            <excluded>true</excluded>
        </dependency>
    </dependencies>
</metadataRepository>

Last, it is possible for you to override the metadata version of a particular module. This may be interesting if there’s no specific metadata available for the particular version of the library that you use, but that you know that a version works:

Specifying the metadata version to use for a particular library

<metadataRepository>
    <enabled>true</enabled>
    <localPath>${project.basedir}/config-directory</localPath>
    <dependencies>
        <dependency>
            <groupId>org.graalvm.internal</groupId>
            <artifactId>library-with-reflection</artifactId>
            <metadataVersion>2</metadataVersion>
        </dependency>
    </dependencies>
</metadataRepository>

Javadocs

In addition, you can consult the Javadocs of the plugin.