Compilare immagini native

Utilizzando le librerie client di Cloud per Java, puoi compilare le applicazioni come immagini native. Questo approccio offre vantaggi in termini di prestazioni alla tua applicazione sfruttando la compilazione AOT per ridurre il tempo di avvio a freddo e l'utilizzo di memoria dell'applicazione.

Versioni della libreria client

Assicurati di utilizzare la versione 25.4.0 o successive dell'elenco dei materiali delle librerie cloud (libraries-bom) o di utilizzare librerie client pubblicate dopo maggio 2022.

La maggior parte degli utenti gestisce le versioni delle librerie client utilizzando libraries-bom. Questo è un modo semplice per verificare che le versioni di tutte le librerie client del tuo progetto siano compatibili tra loro e aggiornate.

Per saperne di più sull'applicazione di libraries-bom al tuo progetto su Maven e Gradle, consulta Aggiornare il progetto per utilizzare la distinta materiali.

Librerie supportate

Le librerie client di Google Cloud stabili per Java elencate nella tabella delle API supportate supportano la compilazione di immagini native.

Prima di iniziare

Per utilizzare la compilazione nativa delle immagini con le librerie client di Google Cloud per Java desiderate, segui questi passaggi preliminari:

  1. Se non l'hai ancora fatto, crea un Google Cloud progetto.

  2. Installa Google Cloud CLI, che ti consente di eseguire l'esempio con le credenziali del tuo progetto.

  3. Dopo aver installato Google Cloud CLI, accedi con le Credenziali predefinite dell'applicazione utilizzando il seguente comando:

    gcloud auth application-default login

  4. Installa una distribuzione JDK appropriata, ad esempio GraalVM.

  5. Assicurati di aver installato l'estensione dell'immagine nativa eseguendo questo comando:

    gu install native-image

  6. Verifica che la versione predefinita di Java sia impostata correttamente eseguendo java -version in un terminale. L'output è simile al seguente:

    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)

Creare un'applicazione come immagine nativa

Le seguenti istruzioni utilizzano i plug-in degli strumenti di compilazione nativi per creare un'applicazione come immagine nativa.

Istruzioni per la configurazione di Maven

  1. Copia e incolla questo testo nel POM della tua applicazione per utilizzare il plug-in Maven nativo per creare l'immagine nativa dell'applicazione. Assicurati di sostituire MAIN_CLASS con il nome della tua classe principale e VERSION con la versione del plug-in Maven nativo, ad esempio 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. Esegui mvn package -Pnative per generare l'immagine nativa nella cartella ./target.

  3. Esegui l'applicazione come qualsiasi eseguibile. Ad esempio, ./target/$IMAGE_NAME. Il plug-in utilizza per impostazione predefinita l'ID artefatto del progetto.

Istruzioni per la configurazione di Gradle

  1. Imposta la classe principale della tua applicazione incollando il seguente testo nel file build.gradle.

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

  2. Aggiungi il plug-in native-gradle come descritto in Aggiunta del plug-in.

  3. Chiama ./gradlew nativeCompile per creare l'immagine nativa nella directory ./build/native/nativeCompile.

  4. Esegui l'applicazione come eseguibile. Ad esempio, ./build/native/nativeCompile/$PROJECT_NAME. Con il plug-in, il nome dell'immagine viene impostato automaticamente sul nome del progetto.

Problemi comuni

Compatibilità con SLF4J

Se esegui la compilazione di immagini native su una libreria client con la dipendenza SLF4J, potresti visualizzare il seguente errore in fase di compilazione.

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.

Aggiungi --initialize-at-run-time=io.grpc.netty.shaded.io.netty al file META-INF/native-image/$GROUP_ID/$ARTIFACT_ID/native-image.properties per risolvere il problema.

Tuttavia, questa configurazione potrebbe comportare un costo in termini di prestazioni per l'immagine nativa generata, a seconda del percorso del codice seguito dalla tua applicazione.

In alternativa, puoi utilizzare una libreria di logging diversa, ad esempio Flogger o la libreria java.util.logging.

Domande

Segnala eventuali problemi e domande relativi alla compilazione di immagini native Java dalla pagina dei problemi di GitHub.

Passaggi successivi