Compiler des images natives

Les bibliothèques clientes Cloud pour Java vous permettent de compiler des applications sous forme d'images natives. Cette approche offre des avantages en termes de performances à votre application en tirant parti de la compilation anticipée pour réduire le temps de démarrage à froid et l'empreinte mémoire de votre application.

Versions des bibliothèques clientes

Assurez-vous d'utiliser la version 25.4.0 ou ultérieure de la nomenclature des bibliothèques Cloud (libraries-bom) ou des bibliothèques clientes publiées après mai 2022.

La plupart des utilisateurs gèrent les versions de leur bibliothèque cliente à l'aide de libraries-bom. Il s'agit d'un moyen simple de vérifier que les versions de toutes les bibliothèques clientes de votre projet sont compatibles entre elles et à jour.

Pour en savoir plus sur l'application de libraries-bom à votre projet sur Maven et Gradle, consultez Mettre à jour votre projet pour utiliser la BOM.

Bibliothèques prises en charge

Les bibliothèques clientes Google Cloud stables pour Java listées dans le tableau des API compatibles sont compatibles avec la compilation d'images natives.

Avant de commencer

Pour utiliser la compilation d'images natives avec les bibliothèques clientes Google Cloud pour Java souhaitées, suivez ces étapes préalables :

  1. Si ce n'est pas déjà fait, créez un Google Cloud projet.

  2. Installez la Google Cloud CLI, qui vous permet d'exécuter l'exemple avec les identifiants de votre projet.

  3. Après avoir installé la Google Cloud CLI, connectez-vous avec les Identifiants par défaut de l'application à l'aide de la commande suivante :

    gcloud auth application-default login

  4. Installez une distribution JDK appropriée, telle que GraalVM.

  5. Assurez-vous d'avoir installé l'extension d'image native en exécutant la commande suivante :

    gu install native-image

  6. Vérifiez que la version par défaut de Java est correctement définie en exécutant java -version dans un terminal. Le résultat ressemble à ce qui suit :

    java -version
openjdk version "17.0.9" 2023-10-17
OpenJDK Runtime Environment GraalVM CE 17.0.9+9.1 (build 17.0.9+9-jvmci-23.0-b22)
OpenJDK 64-Bit Server VM GraalVM CE 17.0.9+9.1 (build 17.0.9+9-jvmci-23.0-b22, mixed mode, sharing)

Créer une application en tant qu'image native

Les instructions suivantes utilisent les plug-ins d'outils de compilation natifs pour compiler une application en tant qu'image native.

Instructions de configuration de Maven

  1. Copiez et collez ce texte dans le fichier POM de votre application pour utiliser le plug-in Maven natif afin de créer l'image native de l'application. Veillez à remplacer MAIN_CLASS par le nom de votre classe principale et VERSION par la version du plug-in Maven natif, par exemple 0.10.1.

    <profiles>
    <profile>
        <id>native</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.graalvm.buildtools</groupId>
                    <artifactId>native-maven-plugin</artifactId>
                    <version>VERSION</version>
                    <extensions>true</extensions>
                    <configuration>
                        <mainClass>$MAIN_CLASS</mainClass>
                        <buildArgs>
                            <buildArg>--no-fallback</buildArg>
                            <buildArg>--no-server</buildArg>
                        </buildArgs>
                    </configuration>
                    <executions>
                        <execution>
                            <id>build-native</id>
                            <goals>
                                <goal>build</goal>
                            </goals>
                            <phase>package</phase>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

  2. Exécutez mvn package -Pnative pour générer l'image native dans le dossier ./target.

  3. Exécutez l'application comme n'importe quel exécutable. Par exemple, ./target/$IMAGE_NAME. Par défaut, le plug-in utilise l'ID d'artefact du projet.

Instructions de configuration de Gradle

  1. Définissez la classe principale de votre application en collant le texte suivant dans votre fichier build.gradle.

    application {
    mainClass.set('$MAIN_CLASS')
}

  2. Ajoutez le plug-in native-gradle comme décrit dans Ajouter le plug-in.

  3. Appelez ./gradlew nativeCompile pour compiler l'image native dans le répertoire ./build/native/nativeCompile.

  4. Exécutez l'application en tant qu'exécutable. Par exemple, ./build/native/nativeCompile/$PROJECT_NAME. Avec le plug-in, le nom de l'image est défini par défaut sur le nom du projet.

Problèmes courants

Compatibilité SLF4J

Si vous effectuez la compilation d'image native sur une bibliothèque cliente avec la dépendance SLF4J, l'erreur de compilation suivante peut s'afficher.

Fatal error: com.oracle.graal.pointsto.util.AnalysisError$ParsingError: Error encountered while parsing io.grpc.netty.shaded.io.netty.util.internal.SystemPropertyUtil.getBoolean(java.lang.String, boolean)
Parsing context:
   at io.grpc.netty.shaded.io.netty.util.internal.SystemPropertyUtil.getBoolean(SystemPropertyUtil.java:96)
   at io.grpc.netty.shaded.io.netty.channel.epoll.Epoll.<clinit>(Epoll.java:33)
   at org.graalvm.nativeimage.pointsto/com.oracle.graal.pointsto.util.AnalysisError.parsingError(AnalysisError.java:153)
...
java.base/java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:165)
Caused by: com.oracle.graal.pointsto.constraints.UnsupportedFeatureException: No instances of org.slf4j.jul.JDK14LoggerAdapter are allowed in the image heap as this class should be initialized at image runtime. To see how this object got instantiated use --trace-object-instantiation=org.slf4j.jul.JDK14LoggerAdapter.

Pour résoudre ce problème, ajoutez --initialize-at-run-time=io.grpc.netty.shaded.io.netty à votre fichier META-INF/native-image/$GROUP_ID/$ARTIFACT_ID/native-image.properties.

Toutefois, cette configuration peut entraîner une perte de performances pour l'image native générée, en fonction du chemin de code suivi par votre application.

Vous pouvez également envisager d'utiliser une autre bibliothèque de journalisation, comme Flogger ou la bibliothèque java.util.logging.

Questions

Veuillez signaler tout problème ou question concernant la compilation d'images natives Java sur la page des problèmes GitHub.

Étape suivante