Configuration

The graalvm { } block inside nucleus.application { } configures GraalVM native-image builds: the toolchain, the output binary, the arguments passed to native-image, the reachability metadata, and the macOS and Windows settings. Every property is lazy and Property-typed. The block is defined on JvmApplication, so it sits alongside mainClass and nativeDistributions.

Enable a native image

Set isEnabled = true and pick a toolchain. A minimal configuration looks like this:

nucleus.application {
    mainClass = "com.example.MainKt"

    graalvm {
        isEnabled = true
        imageName = "myapp"

        // Download the full BellSoft Liberica NIK 25 yourself and install it locally —
        // Gradle's toolchain auto-provisioning does not fetch the NIK variant.
        // In CI, set up the JDK with graalvm/setup-graalvm@v1 first.
        javaLanguageVersion = 25

        buildArgs.addAll(
            "-H:+AddAllCharsets",
            "-Djava.awt.headless=false",
            "-Os",
            "-H:-IncludeMethodData",
        )

        metadataRepository {
            enabled = true           // default
            version = "0.10.6"       // default
            excludedModules.add("com.example:my-lib")
        }
    }
}

graalvm reference

Set build arguments

buildArgs are forwarded verbatim to native-image. These are the arguments most desktop apps need:

Configure the metadata repository

The Nucleus plugin downloads the Oracle GraalVM Reachability Metadata Repository and resolves entries for every runtime dependency on the classpath. The metadataRepository { } sub-block maps to MetadataRepositorySettings.

metadataRepository {
    moduleToConfigVersion.put("io.ktor:ktor-client-core", "3.0.0")
    excludedModules.add("group:noisy-lib")
}

Configure macOS settings

The macOS { } sub-block maps to GraalvmMacOSSettings.

Configure Windows settings

The windows { } sub-block maps to GraalvmWindowsSettings. GraalVM native images on Windows are dynamically linked against the Visual C++ runtime, which is not part of a clean Windows install. Bundling the runtime DLLs next to the executable lets the app start without the Visual C++ Redistributable.

graalvm {
    windows {
        bundleCRuntime = true
        dlls.add("vcruntime140.dll")
    }
}

No release variant

Unlike the JVM build types, GraalVM has no release variant: there is no packageReleaseGraalvmNative and no runReleaseGraalvmNative. The native tasks are packageGraalvmNative and runGraalvmNative. This is intentional:

• ProGuard's dead-code elimination is redundant. native-image already does closed-world dead-code elimination at compile time.
• ProGuard can rename classes that are still referenced by reachability-metadata.json, which breaks the build silently.

Use -Os in buildArgs for size optimization instead of ProGuard.

What's next

• GraalVM overview — what native-image gives a Nucleus app.
• Automatic metadata — the five metadata layers Nucleus assembles for you.
• Tasks and CI — the Gradle tasks and CI setup for native builds.
• Gradle DSL reference — the full nucleus { } surface.