plugins {
- // ...
-
- // Apply GraalVM Native Image plugin
id 'org.graalvm.buildtools.native' version '0.9.29-SNAPSHOT'
}This guide shows how to get started with the Gradle plugin for GraalVM Native Image and build a native executable for a Java application.
You will create a sample application, enable the plugin, add support for dynamic features, run JUnit tests, and build a native executable.
+You will create a sample application, enable the plugin, add support for dynamic features, build a native executable, and run JUnit tests.
Two ways of building a native executable using the plugin will be demonstrated:
@@ -611,7 +606,7 @@plugins {
- // ...
-
- // Apply GraalVM Native Image plugin
id 'org.graalvm.buildtools.native' version '0.9.29-SNAPSHOT'
}plugins {
- // ...
-
- // Apply GraalVM Native Image plugin
id("org.graalvm.buildtools.native") version "0.9.29-SNAPSHOT"
}Another thing to note here: the plugin may not be able to properly detect the GraalVM installation, because of limitations in Gradle. -If you want to use Oracle GraalVM, or a particular version of GraalVM and Java, you need to explicitly tell this in plugin’s configuration. -For example:
-graalvmNative {
- binaries {
- main {
- javaLauncher = javaToolchains.launcherFor {
- languageVersion = JavaLanguageVersion.of(11)
- vendor = JvmVendorSpec.matching("Oracle GraalVM")
- }
- }
- }
}graalvmNative {
- binaries {
- main {
- javaLauncher = javaToolchains.launcherFor {
- languageVersion = JavaLanguageVersion.of(11)
- vendor = JvmVendorSpec.matching("Oracle GraalVM")
- }
- }
- }
-}The workaround to this is to disable toolchain detection with this command toolchainDetection = false.
Compile the project and build a native executable at one step:
./fortune/build/native/nativeCompile/fortune
The application starts and prints a random quote.
Configuring the graalvmNative plugin to automatically detect resources (resources.autodetect()) to be included in a binary is one way to make this example work.
Using resources.autodetect() works because the application uses resources (fortunes.json) which are directly available in the src/main/resources location.
To see the benefits of running your application as a native executable, time how long it takes and compare the results with running as a Java application.
You can customize the plugin. For example, change the name of the native executable and pass additional parameters to the plugin in the build.gradle file, as follows:
-graalvmNative {
- binaries {
- main {
- imageName.set('fortuneteller')
- buildArgs.add('--verbose')
- }
- }
-}graalvmNative {
- binaries {
- main {
- imageName.set("fortuneteller")
- buildArgs.add("--verbose")
- }
- }
-}The native executable then will be called fortuneteller.
-Notice how you can pass additional arguments to the native-image tool using the buildArgs.add syntax.
If you need to test collecting metadata with the agent, add the -Pagent option to the test and nativeTest task invocations:
Run the tests on the JVM with the agent:
-./gradlew -Pagent testIt runs your application on the JVM with the agent, collects the metadata and uses it for testing on native-image.
-The generated configuration files (containing the metadata) can be found in the ${buildDir}/native/agent-output/${taskName} directory.
-In this case, the plugin also substitutes {output_dir} in the agent options to point to this directory.
Build a native executable using the metadata collected by the agent:
-./gradlew -Pagent nativeTestNote that if your application does not call any classes dynamically at run time, the execution with the agent is needless.
-Your workflow, in that case, is just ./gradlew nativeRun.
This guide shows how to get started with the Maven plugin for GraalVM Native Image and build a native executable for a Java application.
You will create a sample application, enable the plugin, add support for dynamic features, run JUnit tests, and build a native executable.
+You will create a sample application, enable the plugin, add support for dynamic features, build a native executable, and run JUnit tests.
Create a new Java project with Maven in your favorite IDE, called Fortune and make sure to choose +
Create a new Java project with Maven in your favorite IDE, called Fortune, in the package named demo. Make sure to choose JUnit Jupiter as the test engine. The pom.xml file should look similar to the following.
package demo;
@@ -632,16 +627,16 @@ FasterXML Jackson
+
Add the FasterXML Jackson
dependency that provide functionality to read and write JSON, data bindings (used in the demo application). Open the
pom.xml file (a Maven configuration file), and insert the following in the <dependencies> section:
- <dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>2.16.0</version>
- </dependency>
+<dependency>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ <version>2.16.0</version>
+</dependency>
@@ -762,8 +757,7 @@
+
+
+
<<<<<<< HEAD +This demo application and requires metadata before building a native executable. +You do not have to configure anything manually: the plugin can generate the required configuration for you by injecting the tracing agent at package time.
This demo application is a little more complicated than HelloWorld, and requires metadata before building a native
-executable. You do not have to configure anything manually as the plugin can generate the required metadata for you by
-injecting the tracing agent at
-package time. The agent is disabled by default, and can be enabled in project’s pom.xml file or via the command line.
This demo application requires metadata before building a native executable. You do not have to configure anything manually: the plugin can generate the required configuration for you by injecting the tracing agent at package time. +>>>>>>> 24e5db3b (Remove extra word) +The agent is disabled by default, and can be enabled in project’s pom.xml file or via the command line.
To enable the agent via the pom.xml file, specify <enabled>true</enabled> in the native-maven-plugin plugin
-configuration:
To enable the agent via the pom.xml file, specify <enabled>true</enabled> in the native-maven-plugin plugin configuration:
<configuration>
- <fallback>false</fallback>
- <agent>
- <enabled>true</enabled>
- </agent>
- </configuration><configuration>
+ <fallback>false</fallback>
+ <agent>
+ <enabled>true</enabled>
+ </agent>
+</configuration>To enable the agent via the command line, pass the -Dagent=true option when running Maven.
So your next step is to run with the agent.
-To enable the agent via the command line, pass the -Dagent=true option when running Maven.
Before running with the agent, register a separate Mojo execution in the native profile which allows forking the
-Java process. It is required to run your application with the agent.
Before running with the agent, register a separate Mojo execution in the native profile which allows forking the Java process.
+It is required to run your application with the agent.
<plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>exec-maven-plugin</artifactId>
- <version>3.1.1</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>
- <execution>
- <id>native</id>
- <goals>
- <goal>exec</goal>
- </goals>
- <configuration>
- <executable>${project.build.directory}/${imageName}</executable>
- <workingDirectory>${project.build.directory}</workingDirectory>
- </configuration>
- </execution>
- </executions>
- </plugin><plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>exec-maven-plugin</artifactId>
+ <version>3.1.1</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>
+ <execution>
+ <id>native</id>
+ <goals>
+ <goal>exec</goal>
+ </goals>
+ <configuration>
+ <executable>${project.build.directory}/${imageName}</executable>
+ <workingDirectory>${project.build.directory}</workingDirectory>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>Now you are all set to to build a native executable from a Java application the plugin.
+Now you are all set to to build a native executable.
Compile the project on the JVM to create a runnable JAR with all dependencies. Open a terminal window and, from the root application directory, run:
@@ -919,8 +911,7 @@When the command completes a native executable, fortune, is created in the target directory of the project and -ready for use.
+When the command completes, a native executable, fortune, is created in the target directory of the project and ready for use.
The executable’s name is derived from the artifact ID, but you can specify any custom name in native-maven-plugin
@@ -928,13 +919,13 @@
<configuration>
- <fallback>false</fallback>
- <imageName>fortuneteller</imageName>
- <agent>
- <enabled>true</enabled>
- </agent>
- </configuration><configuration>
+ <imageName>fortuneteller</imageName>
+ <fallback>false</fallback>
+ <agent>
+ <enabled>true</enabled>
+ </agent>
+</configuration>./target/fortune
mvn -Pnative exec:exec@nativeThe application starts and prints a random quote.
To see the benefits of running your application as a native executable, time how long it takes and compare the results
-with running on the JVM.
== Add JUnit Testing
The Maven plugin for GraalVM Native Image can run JUnit Platform tests on a native executable. @@ -974,33 +957,35 @@
Enable extensions in the plugin’s configuration,
-<extensions>true</extensions>:
Enable extensions in the plugin’s configuration, <extensions>true</extensions>:
<plugin>
- <groupId>org.graalvm.buildtools</groupId>
- <artifactId>native-maven-plugin</artifactId>
- <version>${native.maven.plugin.version}</version>
- <extensions>true</extensions><plugin>
+ <groupId>org.graalvm.buildtools</groupId>
+ <artifactId>native-maven-plugin</artifactId>
+ <version>${native.maven.plugin.version}</version>
+ <extensions>true</extensions>
+ ...
+</plugin>Add an explicit dependency on the junit-platform-launcher artifact to the dependencies section of your native
-profile configuration as in the following example:
Add an explicit dependency on the junit-platform-launcher artifact in the dependencies section of your native profile configuration as in the following example:
<profile>
- <id>native</id>
- <dependencies>
- <dependency>
- <groupId>org.junit.platform</groupId>
- <artifactId>junit-platform-launcher</artifactId>
- <version>1.10.0</version>
- <scope>test</scope>
- </dependency>
- </dependencies><profile>
+ <id>native</id>
+ <dependencies>
+ <dependency>
+ <groupId>org.junit.platform</groupId>
+ <artifactId>junit-platform-launcher</artifactId>
+ <version>1.10.0</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ ...
+</profile>Run native tests:
+Run JUnit tests:
mvn -Pnative -Dagent testRun -Pnative profile will then build and run native tests. Include the -Dagent is this is not enabled in the
-pom.xml file.
The -Pnative profile will then build and run JUnit tests.
=== Summary
+The Maven plugin for GraalVM Native Image adds support for building and testing native executables using Apache Maven™. The plugin has many features, described in the plugin reference documentation.
Note that if your application does not call any classes dynamically at run time, the execution with the agent is needless.
-Your workflow, in that case, is just mvn clean -Pnative package.