The Native Build Tools project provides plugins for different build tools to add support for building and testing native applications written in Java (or any other language compiled to JVM bytecode).

Most notably, this is the official source for integrating with the GraalVM Native Image.

Please refer to the following pages for build tool specific documentation:

This release of Native Build Tools ships with the GraalVM reachability metadata repository release 0.3.4.

If you are interested in contributing, please refer to the Git repository.

If you are using alternative build systems, see Useful Hints for Alternative Build Systems.

Changelog

Release 0.9.27

  • Update JUnit configuration for native testing on GraalVM for JDK 21 with --strict-image-heap mode.

  • Fix path escaping problem for Windows users

Release 0.9.26

  • Relax GraalVM version check for dev versions

  • Prepare plugins for release of GraalVM for JDK 21. They no longer deploy any experimental options.

  • Bump Java compliance of the plugins from Java 8+ to Java 11+.

  • Fix compatibility with Maven 3.9.

Gradle plugin

  • Fix compatibility with Gradle 8.3

Release 0.9.25

  • Upgrade metadata to 0.3.4

Release 0.9.24

  • Upgrade metadata to 0.3.3

Gradle plugin

  • Add support for PGO

Release 0.9.23

  • Upgrade metadata to 0.3.2

  • Display the GraalVM logo on the generated NBT docs

Gradle plugin

  • Remove use of GFileUtils

  • Fix "collect reachability metadata" with config cache

Release 0.9.22

  • Upgrade metadata to 0.3.0

  • Add support for default-for attribute

Gradle plugin

  • Fix lookup of metadata repository

Release 0.9.21

  • Deprecate requiredVersion check without replacement.

Gradle plugin

  • Bump minimal version of Gradle to 7.4

  • Fix compatibility with Gradle’s configuration cache (requires Gradle 7.5+)

  • Remove use of deprecated Gradle APIs

  • [Behavior change] Toolchain detection is now disabled by default

Maven plugin

  • Add a new native:write-args-file goal that can be used to write the arguments passed to native-image to a file

Release 0.9.20

Gradle plugin

  • Fix collectReachabilityMetadata not being thread-safe

  • Add an option to configure the maximum number of images which can be built in parallel

  • Fix GraalVM version check being too strict

Maven plugin

  • Add agent modes to Maven plugin

Release 0.9.19

Gradle plugin

  • Fix nativeCompile being out-of-date whenever native runtime arguments change

  • Fix GraalVM metadata repository not downloaded from project repositories by default

Maven plugin

Release 0.9.18

  • Trim GraalVM version to fix Windows support

  • Add tests for NativeImageUtils.escapeArg

  • Do not escape quoted regexp args when using argsfile

  • Upgrade to GraalVM metadata repository 0.2.5

Release 0.9.17

  • Add a requiredVersion property to check the minimal GraalVM version

  • Make GraalVM installation check lazy

Release 0.9.16

  • Fixed regression with a reachability-metadata repository

Release 0.9.15

  • Upgrade to GraalVM metadata repository 0.2.3.

  • Ship the metadata repository as an artifact alongside the plugin

  • Add ability to collect GraalVM metadata of dependencies to a custom location

Gradle plugin

  • Improved diagnostics to help users figure out what GraalVM toolchain was selected

Release 0.9.14

Gradle plugin

  • Add ability to set environment variables to the native image builder process

  • Argument files are now stored in the build directory (workaround for absolute path issue on Windows with older GraalVM versions)

Maven plugin

  • Added native:compile forking goal that can be started from the command line as mvn native:compile.

  • Deprecated build goal in favour of compile-no-fork goal. This goal should now be used for attaching to the package phase in pom.xml. Attaching the build goal will (for now) produce a runtime warning.

  • Argument files are now stored in the target directory (workaround for absolute path issue on Windows with older GraalVM versions).

  • Default and test outputs are now much less noisy.

  • When running tests in JVM mode with the native-image-agent, GraalVM’s java executable is now always used.

  • Maven plugin now shouldn’t require that JVM running it must be GraalVM.

Release 0.9.13

Gradle plugin

  • Reverted a change in the NativeImagePlugin that removed publicly accessible constants. This should prevent breakage of external plugins.

JUnit testing support

  • Adapted the JUnit automatic metadata registration to changes in annotation handling on newer native image versions.

Release 0.9.12

Gradle plugin

  • Completely reworked agent support - BREAKING CHANGE

  • The agent block is no longer tied to the target binary.

  • The agent can now instrument any task that extends JavaForkOptions.

  • Introduced the metadataCopy task.

  • Introduced the concept of agent modes.

    • Under the hood, the agent mode dictates what options are passed to the agent and how metadata produced by multiple runs get merged.

  • Added excludeConfig configuration option that allows skipping of configuration files that are present in dependencies.

  • useArgFile is now set to true by default only on Windows.

  • Added quickBuild configuration option.

Maven plugin

  • Added support for GraalVM Reachability Metadata Repository.

  • Completely reworked Maven plugin (should fix many of previous issues and inconsistencies between main and test builds).

  • Added classesDirectory, debug, fallback, verbose, sharedLibrary, configurationFileDirectories, excludeConfig, quickBuild, and jvmArgs properties in order to match those present in the Gradle plugin.

    See docs for more information.

  • useArgFile is now set to true by default only on Windows.

  • Changed lookup order for native-image discovery — GRAALVM_HOME, JAVA_HOME, PATH.

Release 0.9.11

Maven plugin

  • Fix long classpath issue under Windows when running native tests

  • Inherit environment variables and system properties from the surefire plugin configuration when executing tests

  • Fix invocation of native-image when classpath contains spaces

Gradle plugin

  • Add support for environment variables in native test execution

  • Fix invocation of native-image when classpath contains spaces

  • Add experimental support for the JVM reachability metadata repository

Release 0.9.10

Maven plugin

  • Native testing support can now be explicitly disabled via skipNativeTests.

  • Fixed race condition which prevented the agent files to be generated properly if tests were executed concurrently

  • Documented version compatibility for the JUnit Platform and Maven Surefire plugin.

  • Add support for long classpath by using an argument file when invoking native-image

Gradle plugin

  • Fixed nativeRun not working properly under Windows

  • Fixed race condition which prevented the agent files to be generated properly if tests were executed concurrently

  • Add support for long classpath by using an argument file when invoking native-image

Release 0.9.9

Gradle plugin

  • Fixed resource inference not working on custom binaries

  • Fixed disableToolchainDetection not working if a GraalVM installation isn’t present. Please use graalvmNative.toolchainDetection.set(false) instead.

Release 0.9.8

Gradle plugin

  • [Breaking change] The agent option has been replaced with an agent { …​ } configuration block which includes an enabled property.

  • Toolchain support can now be disabled altogether, which can be useful when using GraalVM Enterprise Edition.

  • Fixed a bug when using a fat jar which assumed that all entries to be repackaged were jars.

  • Agent options are now configurable.

    • Note that the experimental-class-loader-support agent option is no longer added by default.

    • See Configuring agent options for details.

  • Added an option to perform resource detection in classpath entries which contain a native-image/resource-config.json file.

Maven plugin

  • The agent can now be enabled in the POM.

  • Agent options are now configurable.

    • Note that the experimental-class-loader-support agent option is no longer added by default.

    • See Configuring agent options for details.

  • Added an option to perform resource detection in classpath entries which contain a native-image/resource-config.json file.

JUnit Platform Native

  • Builds now correctly fail if a container-level extension or lifecycle method fails — for example, if an @BeforeAll method in a JUnit Jupiter test class throws an exception.

  • Builds no longer fail when tests are aborted — for example, via a failed assumption.

  • Improved documentation for JUnit Platform and Maven Surefire support in the plugins.

Release 0.9.7.1

Bugfixes

Release 0.9.7

Release didn’t include any fixes.

Release 0.9.6

Upgrade to JUnit 5.8

The plugins now depend on JUnit 5.8 which provides an official test listener which is used by these plugins. As a consequence, Maven users will have to configure their builds to enable the plugin extensions:

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

The dependency on junit-platform-native which used to be required pre-0.9.6 can now safely be removed.

For Gradle users, there’s no impact on the configuration, however a good consequence is that the junit-native-platform dependency no longer leaks into your application’s classpath.

Agent support for Maven plugin

The Maven plugin now supports the GraalVM agent to generate configuration files. Please refer to the Maven plugin documentation for details.

Disabling testing support

The Gradle plugin now provides an option to disable testing support. This can be useful if the test framework you are using doesn’t work with this plugin or that you simply don’t want to execute tests natively.

To disable tests, use the graalvmNative configuration block:

graalvmNative {
    testSupport.set(false)
}

Configuring additional test images

The Gradle plugin now supports building multiple test images, which can be used to execute tests natively for more kinds of tests: integration tests, functional tests, …​

For more information, please refer to the Gradle plugin documentation

Release 0.9.5

This release contains, in preparation for supporting more images in the Gradle plugin:

  • The nativeBuild and nativeTest extensions are now deprecated. A top-level container for configuring native images has been introduced. Instead of:

nativeBuild {
   verbose = true
}

you need to use:

graalvmNative {
  binaries {
    main {
      verbose = true
    }
  }
}

and instead of:

nativeTest {
    buildArgs("...")
}

you need to use:

graalvmNative {
  binaries {
    test {
      verbose = true
    }
  }
}

  • The nativeBuild task has been renamed to nativeCompile.

  • The nativeTestBuild task has been renamed to nativeTestCompile.

Both nativeBuild and nativeTestBuild task invocations are still supported but deprecated and will be removed in a future release.

Release 0.9.4

This release works around a limitation for Windows users who encounter an issue with long classpath entries on CLI: the Gradle plugin will now automatically handle this problem by creating a fat jar instead of passing all entries on classpath (this behavior can be disabled) if needed). Maven users will have to configure their build differently to use shading.

In addition to this, we’re now publishing development snapshots of this plugin. For Gradle, you will need to declare this repository in your settings.gradle(.kts) file:

pluginManagement {
    plugins {
        id 'org.graalvm.buildtools.native' version '0.9.5-SNAPSHOT'
    }
    repositories {
        maven {
            url "https://raw.githubusercontent.com/graalvm/native-build-tools/snapshots"
        }
        gradlePluginPortal()
    }
}

For Maven, you need to use this repository configuration:

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

Release 0.9.3

This release contains:

  • Fix for mainClass not being optional (Gradle plugin)

  • Fix for Gradle < 7 failing to determine GraalVM toolchain

  • Gradle plugin now registers proper groups

  • Automatic native-image tool fetching via gu (Gradle plugin)

  • FIxed issue where nativeTest would fail when tests are annotated with Timeout

  • Added a sharedLibrary configuration option for Gradle plugin

  • Removed broken server configuration option from Gradle plugin

  • Added a documentation website with proper CI integration

In addition to those improvements, several behind-the-scenes changes were made:

  • Introduced "Dockerless" Maven plugin functional testing

  • Parallelized Gradle testing in CI

  • Replaced groovy-json with jackson-databind for JSON handling

  • Fixed Github Actions syntax to enable manual workflow invoking

Release 0.9.2

This release contains:

  • Revamped Gradle plugin that is now a lot more idiomatic.

  • Fixes for several issues regarding JUnit testing.

  • Removal of Test Discovery mode from the Maven plugin.

  • Fix for Maven creating empty test images when no tests are present.

  • Added support for Kotlin tests in Gradle.

In addition to those improvements, several behind-the-scenes changes were made in order to ensure better compatibility moving forward:

  • Test coverage has been greatly improved for all subprojects.

  • Build tooling for this repository has been improved significantly.

Note that there has been a breaking change in the Gradle plugin - persistConfig configuration option was removed. Using said option will cause existing builds to break, so users are advised to remove it from their configuration prior to upgrading. System property -DpersistConfig will have no effect going forward.

Release 0.9.1

This release contains:

  • Fixes for most of the known issues regarding Gradle and Maven plugins

  • Massively improved automatic JUnit support as well as initial JUnit Vintage support

  • Improved JavaDoc and tests for the Gradle plugin

Release 0.9.0

Initial release