GraalVM Native Build Tools

The native-maven-plugin (packaged as maven-plugin) translates Maven project state, XML configuration, system properties, dependency scopes, and lifecycle phases into Native Build Tools behavior.

Key functional areas include:

• Goal Surface: Maven goals, lifecycle bindings, support goals, and profile usage.
• Native Image Builds: Build behavior, main-class discovery, skipping, classpath scopes, SBOM, and argument files.
• Configuration Model: Native Image options, command-line properties, parent POM merging, toolchain lookup, and override precedence.
• Native Tests: Native test classpath, discovery, launcher selection, and execution.
• Tracing Agent: Enablement, modes, output, and metadata merge/copy behavior.
• Resources and Metadata: Resource configuration, reachability metadata, missing-metadata reports, schema validation, and entry points.

The native-gradle-plugin module provides the Gradle plugin identified by the ID org.graalvm.buildtools.native. This plugin enables Native Image workflows within Gradle projects by providing the graalvmNative DSL, specialized tasks, and integration with GraalVM's native image capabilities.

To use the plugin, apply it to your Gradle project and configure your native image settings using the graalvmNative extension.

plugins {
    id 'org.graalvm.buildtools.native'
}

The specification is organized into several key areas to help developers find the correct technical details:

• grund.md: The fundamental reason for the project's existence.
• goals.md & non-goals.md: Defines what the project aims to achieve and what is explicitly out of scope.
• requirements.md: Cross-cutting compatibility and support constraints.
• architecture/: Contains the repository component map, dependency directions, and implementation structure.
• functional/: Contains the functional specifications for observable behaviors like native image builds, testing, and resource management.
• decisions/: Records architectural decisions and tradeoffs.
• glossary.md: Domain terms used throughout the specifications.

The common directory is organized into specific modules based on their functional domain:

• common/utils: Manages shared agent configuration models, resource configuration models, classpath and JAR analysis, Native Image command-line utilities, schema validation helpers, JUnit dependency helpers, and shared constants.
• common/graalvm-reachability-metadata: Handles metadata repository access, artifact and module indexes, directory configuration, query objects, version selection, and support for missing metadata commands.
• common/junit-platform-native: Provides JUnit Platform support required inside native test images, including native-image feature registration, test class registration, launcher behavior, and JUnit configuration providers.

This feature enables JUnit Platform testing support for GraalVM Native Image. It allows you to run JUnit tests within a native image.

To use it, the artifact produced by this project must be included on your classpath. You can do this via build tool plugins or manual configuration.

There are two modes of operation:

1. Out of the box: For tests that do not use reflection internally.
2. With the agent run: For tests that use internal reflection. This requires running the native-image-agent to generate necessary configuration.

# Manual configuration if build tool support is missing:
native-image \
    ... \
    --no-fallback \
    --features=org.graalvm.junit.platform.JUnitPlatformFeature \
    org.graalvm.junit.platform.NativeImageJUnitLauncher

The Native Image Gradle Plugin is a Gradle plugin designed to facilitate the building of GraalVM Native Images. It integrates GraalVM Native Image capabilities directly into the Gradle build lifecycle.

For detailed end-user documentation, configuration options, and usage guides, refer to the official documentation site: https://graalvm.github.io/native-build-tools/

The native-maven-plugin is a Maven plugin designed to facilitate the building of GraalVM Native Images. It integrates the Native Image build process directly into the Maven lifecycle.

For detailed end-user documentation, including configuration options and usage guides, refer to the official GraalVM Native Build Tools documentation site: https://graalvm.github.io/native-build-tools/.

Native Build Tools provides Gradle and Maven plugins that automate the complex requirements of building GraalVM Native Image applications. It integrates the following specialized workflows directly into your existing build tool:

• Dependency Management: Automatically passes necessary dependencies to the native-image tool at build time.
• Native Testing: Orchestrates a workflow that builds an executable binary and then executes it to run tests.
• Agent Integration: Handles the extra steps required for the native-image agent to process metadata.
• Reachability Metadata: Automates lookups for reachability metadata from the GraalVM Reachability Metadata Repository.