Configuration

Le bloc graalvm { } à l'intérieur de nucleus.application { } configure les builds native-image GraalVM : la toolchain, le binaire de sortie, les arguments passés à native-image, les métadonnées de reachability et les réglages macOS et Windows. Chaque propriété est paresseuse et typée Property. Le bloc est défini sur JvmApplication, il se place donc à côté de mainClass et nativeDistributions.

Activer une native image

Mettez isEnabled = true. Nucleus provisionne la toolchain pour vous — une configuration minimale ressemble à ceci :

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

    graalvm {
        isEnabled = true
        imageName = "myapp"

        // Optionnel : optimise l'image pour la taille au lieu du -O2 par défaut.
        optimization = NativeImageOptimization.SIZE

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

Provisionner la toolchain

Par défaut, Nucleus télécharge et met en cache GraalVM Community Edition sous <gradle-user-home>/nucleus/graalvm — aucune installation locale ni étape graalvm/setup-graalvm nécessaire. Le téléchargement n'a lieu que lorsqu'une tâche native-image s'exécute réellement : lister les tâches ou synchroniser l'IDE ne télécharge jamais de JDK. Une variable d'environnement GRAALVM_HOME reste prioritaire, à condition qu'elle corresponde à la distribution demandée. Le sous-bloc toolchain { } correspond à GraalvmToolchainSettings.

graalvm {
    toolchain {
        autoDownload = true                              // défaut
        distribution = GraalvmDistribution.COMMUNITY     // défaut
        channel = GraalvmChannel.INNOVATION              // défaut ; LTS pour la ligne à support long terme
        // version = "25"                                // optionnel ; remplace channel
    }
}

Choisir une distribution

Optez pour Oracle GraalVM lorsque vous avez besoin de ses optimisations exclusives — Profile-Guided Optimization, optimization = NativeImageOptimization.LEVEL_3 (-O3), profils inférés par ML, et advancedObfuscation :

graalvm {
    toolchain {
        distribution = GraalvmDistribution.ORACLE
    }
}

Avec la toolchain communautaire par défaut, ces fonctionnalités Oracle se dégradent proprement : -O3, --pgo et -H:AdvancedObfuscation sont ignorés avec un warning au lieu de faire échouer le build, et la tâche runWithPgoInstrument n'est pas enregistrée du tout.

Les répertoires d'installation intègrent la distribution (graalvm-community-jdk-* vs graalvm-jdk-*) : changer de distribution ne réutilise jamais le téléchargement de l'autre, et un GRAALVM_HOME dont la distribution ne correspond pas au DSL est ignoré avec un warning.

Pour builder sur une autre toolchain communautaire (Liberica NIK, Mandrel), pointez GRAALVM_HOME dessus, ou mettez autoDownload = false et choisissez un jvmVendor.

Référence de graalvm

Choisir un garbage collector

Le collecteur est fixé au build pour les images natives. Laissez-le non défini pour Serial (le bon défaut pour un tas de taille desktop). Ne choisissez G1 que lorsque le tas dépasse ce que Serial peut collecter sans pauses visibles, et uniquement sous Oracle GraalVM Linux :

nucleus.application {
    // Distribution JVM HotSpot (launcher + tâche run)
    garbageCollector = GarbageCollector.Z

    graalvm {
        // Inscrit dans l'image native (--gc=)
        garbageCollector = NativeImageGarbageCollector.G1
    }
}

Valeurs JVM de GarbageCollector : SERIAL, PARALLEL, G1, Z, SHENANDOAH, EPSILON. Les flags sont préfixés pour qu'un -XX:+Use…GC explicite dans jvmArgs l'emporte encore. Non défini : ergonomie du JDK.

Définir les arguments de build

Les buildArgs sont transmis tels quels à native-image et l'emportent sur les propriétés type-safe. Préférez optimization à un -Os/-O* brut et allCharsets à -H:+AddAllCharsets ; réservez buildArgs à tout ce qui n'a pas de propriété dédiée :

Optimiser avec un profil PGO

La Profile-Guided Optimization (Oracle GraalVM uniquement) enregistre la façon dont l'app s'exécute réellement et réinjecte ce profil dans le build suivant. Elle nécessite toolchain { distribution = GraalvmDistribution.ORACLE } ; avec la toolchain communautaire par défaut, runWithPgoInstrument n'est pas enregistrée. Le sous-bloc pgo { } correspond à GraalvmPgoSettings.

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

1. Enregistrer : ./gradlew runWithPgoInstrument construit une image instrumentée, l'exécute et écrit le profil dans profile à la sortie. Exercez les chemins chauds avant de quitter.
2. Committez le fichier .iprof. Les builds complets (createGraalvmNativeDistributable, runGraalvmNativeDistributable, tâches de packaging) l'appliquent automatiquement en --pgo=<profile>. Le chemin quick-build runGraalvmNative saute la PGO et l'obfuscation avancée.

Désactivez un profil enregistré pour un seul build avec -Pnucleus.graalvm.pgo=off. Sur les toolchains communautaires (GraalVM CE, Liberica NIK, Mandrel), --pgo n'est pas disponible : un profil enregistré est ignoré avec un avertissement, et la tâche runWithPgoInstrument n'existe pas.

Configurer le repository de metadata

Le plugin Nucleus télécharge l' Oracle GraalVM Reachability Metadata Repository et résout les entrées de chaque dépendance runtime du classpath. Le sous-bloc metadataRepository { } correspond à MetadataRepositorySettings.

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

Configurer les réglages macOS

Sous macOS (arm64), les images natives du backend Tao (par défaut) se construisent sur la toolchain auto-provisionnée (GraalVM CE par défaut). Le backend AWT, déprécié, nécessite encore BellSoft Liberica NIK. Les Mac Intel retombent sur Liberica NIK.

Le sous-bloc macOS { } correspond à GraalvmMacOSSettings.

Configurer les réglages Windows

Le sous-bloc windows { } correspond à GraalvmWindowsSettings. Sur Windows, les native images GraalVM sont liées dynamiquement au runtime Visual C++, qui ne fait pas partie d'une installation Windows propre. Regrouper les DLL du runtime à côté de l'exécutable permet à l'app de démarrer sans le Visual C++ Redistributable.

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

Pas de variant release

Contrairement aux build types JVM, GraalVM n'a pas de variant release : il n'existe ni packageReleaseGraalvmNative ni runReleaseGraalvmNative. Les tâches natives publiques suivent le pipeline JVM (runGraalvmNative, createGraalvmNativeDistributable, …). C'est volontaire :

• L'élimination de code mort de ProGuard est redondante. native-image fait déjà une élimination de code mort en monde fermé au moment de la compilation.
• ProGuard peut renommer des classes encore référencées par reachability-metadata.json, ce qui casse le build silencieusement.

Utilisez optimization = NativeImageOptimization.SIZE pour optimiser la taille plutôt que ProGuard.

Et ensuite

• Vue d'ensemble GraalVM — ce que native-image apporte à une app Nucleus.
• Metadata automatique — les cinq couches de metadata que Nucleus assemble pour vous.
• Tâches et CI — les tâches Gradle et la configuration CI pour les builds natifs.
• Référence du DSL Gradle — toute la surface nucleus { }.