Native KBean

Creates native executables.

A native image is an executable file created from Java bytecode. This KBean allows creating native images from executable jars generated from the project.

NativeKBean enables native compilation for the project and base KBeans.

Key Features

• Compiles classes into native executables.
• Automatically applies AOT metadata.
• Simplifies resource inclusion.
• Handles static linkage with minimal configuration.

Usage

The NativeKBean works with either project or base KBeans to compile your Java application into a native executable using GraalVM native-image.

Basic Invocation

jeka native: compile

This command: 1. Compiles your project if needed 2. Creates a native executable from the project's main artifact jar 3. Places the executable in the output directory (same location as the jar, but without .jar extension)

Configuration

Configure the KBean through jeka.properties or programmatically in your KBean class.

Example configuration in jeka.properties:

@native.includeAllResources=true
@native.staticLink=MUSL
@native.metadataRepoVersion=0.10.3
@native.args=--verbose --no-fallback

Available Configuration Options:

• args: Extra arguments to pass to the native-image compiler (e.g., --verbose --no-fallback)
• staticLink: Static linkage mode for native libraries
  • NONE (default): No static linking
  • MUSL: Static linking with MUSL libc
  • GLIBC: Static linking with GLIBC
• useMetadataRepo: Uses predefined exploratory AOT metadata from the standard repository (default: true)
• metadataRepoVersion: Version of the GraalVM reachability metadata repository to use
• includeMainClassArg: Whether to specify the main class in command line arguments (default: true)
• includeAllResources: Includes all resources in the native image (default: false)

Programmatic Configuration

You can also configure the NativeKBean programmatically:

@JkDefClasspath("com.example:my-lib:1.0")
public class Build extends KBean {

    final NativeKBean nativeKBean = load(NativeKBean.class);

    Build() {
        nativeKBean.includeAllResources = true;
        nativeKBean.staticLink = JkNativeCompilation.StaticLink.MUSL;
        nativeKBean.args = "--verbose --no-fallback";
    }
}

AOT Metadata

The KBean automatically handles AOT (Ahead-Of-Time) metadata required for reflection, resources, and JNI access in native images:

• By default, it uses the GraalVM reachability metadata repository
• The metadata repository version can be specified via metadataRepoVersion
• Disable with @native.useMetadataRepo=false if you provide your own metadata

Requirements

• GraalVM is automatically downloaded if not already available
• The project or base KBean must be present in your build

See native API for low-level API details.

Summary

Creates native executables.

A native image is an executable file created from Java bytecode. This KBean allows creating native images from executable jars generated from the project.

This KBean exposes the following fields:

Field	Description
args [String]	Extra arguments to pass to native-image compiler.
staticLink [enum:JkNativeCompilation$StaticLink]	Specifies whether the generated executable must be statically linked with native libs.
useMetadataRepo [boolean]	Uses predefined exploratory AOT metadata defined in the standard repository.
metadataRepoVersion [String]	Version of the predefined exploratory AOT metadata repository.
includeMainClassArg [boolean]	If false, the main class won't be specified in command line arguments. This means that it is expected to be mentioned in aot config files.
includeAllResources [boolean]	If true, all resources will be included in the native image.

This KBean exposes the following methods:

Method	Description
compile	Creates a native image from the project's main artifact jar. Builds the artifact first if none exists.