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. Nucleus provisions the toolchain for you — a minimal configuration looks like this:

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

    graalvm {
        isEnabled = true
        imageName = "myapp"

        // Optional: optimize the image for size instead of the default -O2.
        optimization = NativeImageOptimization.SIZE

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

Provision the toolchain

By default Nucleus downloads and caches GraalVM Community Edition under <gradle-user-home>/nucleus/graalvm — no local install and no graalvm/setup-graalvm step needed. The download happens only when a native-image task actually runs: listing tasks or syncing the IDE never pulls a JDK. A GRAALVM_HOME environment variable takes precedence, provided it matches the requested distribution. The toolchain { } sub-block maps to GraalvmToolchainSettings.

graalvm {
    toolchain {
        autoDownload = true                              // default
        distribution = GraalvmDistribution.COMMUNITY     // default
        channel = GraalvmChannel.INNOVATION              // default; LTS for the long-term-support line
        // version = "25"                                // optional; overrides channel
    }
}

Choose a distribution

Opt into Oracle GraalVM when you need its exclusive optimizations — Profile-Guided Optimization, optimization = NativeImageOptimization.LEVEL_3 (-O3), ML-inferred profiles, and advancedObfuscation:

graalvm {
    toolchain {
        distribution = GraalvmDistribution.ORACLE
    }
}

Under the default community toolchain those Oracle-only features degrade gracefully: -O3, --pgo and -H:AdvancedObfuscation are skipped with a warning instead of failing the build, and the runWithPgoInstrument task is not registered at all.

Install directories embed the distribution (graalvm-community-jdk-* vs graalvm-jdk-*), so switching never reuses the other build's download, and a GRAALVM_HOME whose distribution disagrees with the DSL is ignored with a warning.

To build on another community toolchain (Liberica NIK, Mandrel), point GRAALVM_HOME at it, or set autoDownload = false and pick a jvmVendor.

graalvm reference

Set build arguments

buildArgs are forwarded verbatim to native-image and win over the type-safe properties. Prefer optimization over a raw -Os/-O* and allCharsets over -H:+AddAllCharsets; reach for buildArgs for anything without a dedicated property:

Optimize with a PGO profile

Profile-Guided Optimization (Oracle GraalVM only) records how the app actually runs and feeds that profile back into the next build. It requires toolchain { distribution = GraalvmDistribution.ORACLE }; under the default community toolchain runWithPgoInstrument is not registered. The pgo { } sub-block maps to GraalvmPgoSettings.

graalvm {
    pgo {
        enabled = true                                                    // default
        profile = layout.projectDirectory.file("graalvm/pgo/default.iprof") // default
    }
}

1. Record: ./gradlew runWithPgoInstrument builds an instrumented image, runs it, and writes the profile to profile on exit. Exercise the hot paths before quitting.
2. Commit the .iprof file. Later packageGraalvmNative / runGraalvmNative builds apply it automatically as --pgo=<profile>.

Disable a recorded profile for one build with -Pnucleus.graalvm.pgo=off. On community toolchains (GraalVM CE, Liberica NIK, Mandrel) --pgo is unavailable: a recorded profile is ignored with a warning, and the runWithPgoInstrument task does not exist.

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

On macOS (arm64), native images on the default Tao backend build on the auto-provisioned toolchain (GraalVM CE by default). The deprecated AWT backend still requires BellSoft Liberica NIK. Intel Macs fall back to Liberica NIK.

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 optimization = NativeImageOptimization.SIZE 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.