Compilar imagens nativas

Usando as bibliotecas de cliente do Cloud para Java, é possível compilar aplicativos como imagens nativas. Essa abordagem oferece benefícios de performance ao seu aplicativo usando a compilação antecipada para reduzir o tempo de inicialização a frio e a ocupação de memória do aplicativo.

Versões da biblioteca de cliente

Use a versão 25.4.0 ou mais recente da lista de materiais das bibliotecas do Cloud (libraries-bom) ou bibliotecas de cliente publicadas após maio de 2022.

A maioria dos usuários gerencia as versões da biblioteca de cliente usando o libraries-bom. Essa é uma maneira fácil de verificar se as versões de todas as bibliotecas de cliente no seu projeto são compatíveis entre si e estão atualizadas.

Para mais informações sobre como aplicar a libraries-bom ao seu projeto no Maven e no Gradle, consulte Atualizar seu projeto para usar a BOM.

Bibliotecas permitidas

As bibliotecas de cliente do Google Cloud para Java estáveis listadas na tabela de APIs compatíveis oferecem suporte à compilação de imagens nativas.

Antes de começar

Para usar a compilação de imagens nativas com as bibliotecas de cliente do Google Cloud para Java desejadas, siga estas etapas de pré-requisito:

  1. Se você ainda não tiver feito isso, crie um Google Cloud projeto.

  2. Instale a Google Cloud CLI, que permite executar a amostra com as credenciais do seu projeto.

  3. Depois de instalar a Google Cloud CLI, faça login com o Application Default Credentials usando o seguinte comando:

    gcloud auth application-default login

  4. Instale uma distribuição do JDK adequada, como o GraalVM.

  5. Verifique se você instalou a extensão de imagem nativa executando o seguinte comando:

    gu install native-image

  6. Verifique se a versão padrão do Java está definida corretamente executando java -version em um terminal. O resultado será o seguinte:

    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)

Criar um aplicativo como uma imagem nativa

As instruções a seguir usam os plug-ins de ferramentas de build nativas para criar um aplicativo como uma imagem nativa.

Instruções de configuração do Maven

  1. Copie e cole esse texto no POM do aplicativo para usar o plug-in do Maven nativo para criar a imagem nativa do aplicativo. Substitua MAIN_CLASS pelo nome da sua classe principal e VERSION pela versão do plug-in nativo do Maven, como 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. Execute mvn package -Pnative para gerar a imagem nativa na pasta ./target.

  3. Execute o aplicativo como qualquer executável. Por exemplo, ./target/$IMAGE_NAME. O plug-in usa como padrão o ID do artefato do projeto.

Instruções de configuração do Gradle

  1. Cole o texto a seguir no arquivo build.gradle para definir a classe principal do aplicativo.

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

  2. Adicione o plug-in native-gradle conforme descrito em Como adicionar o plug-in.

  3. Chame ./gradlew nativeCompile para criar a imagem nativa no diretório ./build/native/nativeCompile.

  4. Execute o aplicativo como um executável. Por exemplo, ./build/native/nativeCompile/$PROJECT_NAME. Com o plug-in, o nome da imagem é o nome do projeto por padrão.

Problemas comuns

Compatibilidade com SLF4J

Se você estiver realizando a compilação de imagem nativa em uma biblioteca de cliente com a dependência SLF4J, poderá encontrar o seguinte erro de tempo de build.

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.

Adicione --initialize-at-run-time=io.grpc.netty.shaded.io.netty ao arquivo META-INF/native-image/$GROUP_ID/$ARTIFACT_ID/native-image.properties para resolver esse problema.

No entanto, essa configuração pode gerar um custo de desempenho para a imagem nativa gerada, dependendo do caminho de código seguido pelo aplicativo.

Como alternativa, use outra biblioteca de geração de registros, como Flogger ou a biblioteca java.util.logging.

Perguntas

Informe problemas e dúvidas relacionados à compilação de imagens nativas do Java na página de problemas do GitHub.

A seguir