Suporte a arquiteturas de 64 bits

Os apps publicados no Google Play precisam ter suporte a arquiteturas de 64 bits. A adição de uma versão de 64 bits do seu app proporciona melhorias de desempenho e faz com que ele possa ser executado em hardware com 64 bits.

As etapas abaixo garantem que seu app de 32 bits ofereça suporte a dispositivos de 64 bits.

Avaliar o app

Se o app usa apenas código escrito na linguagem de programação Java ou Kotlin, incluindo bibliotecas ou SDKs, ele oferece suporte a dispositivos de 64 bits. Caso seu app use código nativo ou se você não tem certeza disso, avalie o app.

Verificação rápida de status

Acesse o Play Console e confira se as versões atuais estão em conformidade.

O Play Console também vai mostrar avisos que se aplicam às suas versões de rascunho se houver algum problema relacionado ao requisito de 64 bits. A imagem abaixo é um exemplo.

Se um alerta aparecer, consulte as etapas abaixo para oferecer suporte a dispositivos de 64 bits.

O app usa código nativo?

Seu app usa código nativo se ele:

• usa qualquer código C/C++ (nativo);
• vincula-se a qualquer biblioteca nativa de terceiros;
• é feito por um criador de apps de terceiros que usa bibliotecas nativas.

O app inclui bibliotecas de 64 bits?

Inspecione a estrutura do seu arquivo APK. Quando criado, o APK é empacotado com as bibliotecas nativas necessárias para o app. Elas são armazenadas em várias pastas com base na ABI. O app não precisa oferecer suporte a todas as arquiteturas de 64 bits, mas para cada arquitetura nativa de 32 bits com suporte é necessário incluir a de 64 bits correspondente.

Para a arquitetura ARM, as bibliotecas de 32 bits ficam em armeabi-v7a. O equivalente para 64 bits é arm64-v8a.

No caso da arquitetura x86, procure x86 para 32 bits e x86_64 para 64 bits.

Confira se há bibliotecas nativas nas duas pastas. Em resumo:

Dependendo do seu app, os conjuntos de bibliotecas em cada pasta não necessariamente serão os mesmos. O objetivo é garantir a execução correta do app em um ambiente de 64 bits.

Em um caso comum, um APK ou pacote criado para arquiteturas de 32 e 64 bits tem pastas para as duas ABIs, cada uma com um conjunto correspondente de bibliotecas nativas. Se ele não oferece suporte a 64 bits, você provavelmente só encontra uma pasta para a ABI de 32 bits.

Procurar bibliotecas nativas usando o APK Analyzer

O APK Analyzer é uma ferramenta que permite avaliar vários aspectos de um APK. Use esse recurso para encontrar bibliotecas nativas e garantir a presença das bibliotecas de 64 bits.

1. Acesse o Android Studio e abra qualquer projeto.

2. No menu, selecione Build > Analyze APK….

   

3. Escolha o APK que você quer avaliar.

4. Confira se há algum arquivo ".so" na pasta lib. Se não houver nenhum, seu app vai oferecer suporte a dispositivos de 64 bits, e nenhuma outra ação será necessária. Se você encontrar armeabi-v7a ou x86, isso indica que há bibliotecas de 32 bits.

5. Verifique se há arquivos ".so" semelhantes na pasta arm64-v8a ou x86_64.

   

6. Se você não tiver bibliotecas arm64-v8a ou x86_64, atualize seu processo de build para começar a criar e empacotar esses artefatos no seu APK.

7. Se as duas bibliotecas já estiverem sendo empacotadas, teste o app em um hardware de 64 bits.

Procurar bibliotecas nativas descompactando APKs

Os APKs são estruturados como arquivos ZIP. Com a linha de comando ou qualquer outra ferramenta de extração, descompacte o arquivo APK. Dependendo da ferramenta, talvez seja necessário renomeá-lo como .zip.

Em seguida, procure os arquivos extraídos e siga a orientação acima para determinar se o app oferece suporte a dispositivos de 64 bits. Execute o exemplo abaixo na linha de comando:

:: Command Line
> zipinfo -1 YOUR_APK_FILE.apk | grep \.so$
lib/armeabi-v7a/libmain.so
lib/armeabi-v7a/libmono.so
lib/armeabi-v7a/libunity.so
lib/arm64-v8a/libmain.so
lib/arm64-v8a/libmono.so
lib/arm64-v8a/libunity.so

Observe nesse exemplo a presença de bibliotecas armeabi-v7a e arm64-v8a. Isso significa que o app oferece suporte a arquiteturas de 64 bits.

Criar o app com bibliotecas de 64 bits

As instruções abaixo descrevem como criar bibliotecas de 64 bits. Essas etapas abrangem apenas o código de criação e as bibliotecas que você pode criar com base na origem.

Criar com o Gradle ou Android Studio

Como a maioria dos projetos do Android Studio usa o Gradle como sistema de build de base, esta seção se aplica aos dois casos. Para ativar builds para seu código nativo, adicione arm64-v8a e/ou x86_64, dependendo das arquiteturas a que você quer oferecer suporte, à configuração ndk.abiFilters no arquivo "build.gradle" do app:

// Your app's build.gradle
plugins {
  id 'com.android.app'
}

android {
   compileSdkVersion 27
   defaultConfig {
       appId "com.google.example.64bit"
       minSdkVersion 15
       targetSdkVersion 28
       versionCode 1
       versionName "1.0"
       ndk.abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64'
// ...

// Your app's build.gradle
plugins {
    id("com.android.app")
}

android {
    compileSdkVersion(27)
    defaultConfig {
        appId = "com.google.example.64bit"
        minSdkVersion(15)
        targetSdkVersion(28)
        versionCode = 1
        versionName = "1.0"
        ndk {
            abiFilters += listOf("armeabi-v7a","arm64-v8a","x86","x86_64")
        }
// ...

Criar com o CMake

Caso seu app seja criado usando o CMake, é possível programar para ABIs de 64 bits transmitindo arm64-v8a para o parâmetro "-DANDROID_ABI":

:: Command Line
> cmake -DANDROID_ABI=arm64-v8a … or
> cmake -DANDROID_ABI=x86_64 …

Criar com o ndk-build

Caso seu app seja criado com o ndk-build, é possível programar para ABIs de 64 bits modificando o arquivo Application.mk com a variável APP_ABI:

APP_ABI := armeabi-v7a arm64-v8a x86 x86_64

Fazer a portabilidade de código de 32 bits para 64 bits

Caso seu código já esteja sendo executado no computador ou no iOS, você não precisa fazer nenhum trabalho extra para o Android. Se esta for a primeira vez que seu código foi criado para um sistema de 64 bits, o principal problema que você vai precisar resolver é que os ponteiros não se encaixam mais em tipos inteiros de 32 bits, como int.

Atualize o código que armazena ponteiros em tipos como int, unsigned ou uint32_t. Em sistemas Unix, long corresponde ao tamanho do ponteiro, mas isso não acontece no Windows. Então, use os tipos de revelação de intenção uintptr_t ou intptr_t. Use o tipo ptrdiff_t para armazenar a diferença entre dois ponteiros.

Prefira sempre os tipos inteiros de largura fixa específicos definidos em <stdint.h> aos tipos sem largura fixa, como int ou long, mesmo para elementos que não sejam ponteiros.

Use as flags do compilador mostradas abaixo para capturar casos em que seu código faz a conversão incorretamente entre ponteiros e números inteiros:

-Werror=pointer-to-int-cast
-Werror=int-to-pointer-cast
-Werror=shorten-64-to-32

Classes Java com campos int que contêm ponteiros para objetos C/C++ enfrentam o mesmo problema. Procure jint na origem JNI e mude para long na parte em Java e jlong na parte em C++.

Declarações implícitas de funções são muito mais perigosas para código de 64 bits. O C/C++ presume que o tipo de retorno de uma função declarada implicitamente (ou seja, uma função de que o compilador não tenha encontrado uma declaração) é int. Se o tipo de retorno real da sua função for um ponteiro, isso vai funcionar bem em um sistema de 32 bits em que o ponteiro se encaixa em um int. No entanto, em um sistema de 64 bits, o compilador vai eliminar a metade de cima do ponteiro. Exemplo:

// This function returns a pointer:
// extern char* foo();

// If you don't include a header that declares it,
// when the compiler sees this:
char* result = foo();

// Instead of compiling that to:
result = foo();

// It compiles to something equivalent to:
result = foo() & 0xffffffff;

// Which will then cause a SIGSEGV if you try to dereference `result`.

A flag do compilador abaixo transforma avisos implícitos de declaração de função em erros para que você possa encontrar e corrigir esse problema mais facilmente:

-Werror=implicit-function-declaration

Se você tem um conversor inline, reescreva-o ou use uma implementação simples de C/C++.

Se você tiver tamanhos codificados de tipos (8 ou 16 bytes, por exemplo), substitua-os pela expressão sizeof(T) equivalente, como sizeof(void*).

Se for preciso compilar condicionalmente um código diferente para 32 bits e 64 bits, use o #if defined(__LP64__) para diferenças genéricas entre 32 e 64 bits ou __arm__, __aarch64__ (arm64), __i386__ (x86) e __x86_64__ para as arquiteturas específicas com suporte do Android.

Ajuste as strings de formato para funções como printf ou scanf, já que os especificadores tradicionais de formato não permitem especificar tipos de 64 bits de uma forma correta para dispositivos de 32 e 64 bits. As macros PRI e SCN em <inttypes.h> resolvem esse problema. Já PRIxPTR e SCNxPTR servem para ler/gravar ponteiros hex, e PRId64 e SCNd64 para ler/gravar valores de 64 bits de maneira portátil.

Ao mudar, pode ser necessário usar 1ULL para ter uma constante de 64 bits em vez de usar 1, que é apenas de 32 bits.

Mitigar o aumento de tamanho com o Android App Bundle

Adicionar suporte a arquiteturas de 64 bits ao seu app pode aumentar o tamanho do APK. É altamente recomendável que você use o recurso Android App Bundle para minimizar o impacto sobre o tamanho da inclusão de código nativo de 32 e 64 bits no mesmo APK.

Desenvolvedores de jogos

Confira os três mecanismos mais usados que oferecem suporte a 64 bits:

• Unreal desde 2015
• Cocos2d desde 2015
• Unity desde 2018

Desenvolvedores de Unity

Fazer upgrade para versões compatíveis

O Unity oferece suporte a 64 bits nas versões 2018.2 e 2017.4.16.

Se você está usando uma versão do Unity que não oferece suporte a 64 bits, determine a versão para que pretende fazer upgrade e siga os guias (em inglês) do Unity para migrar seu ambiente, garantindo que o app seja atualizado para uma versão capaz de criar bibliotecas de 64 bits. O Unity recomenda fazer upgrade para a versão com LTS mais recente do editor para ter acesso a novos recursos e atualizações.

Confira uma tabela que descreve as várias versões do Unity e o que você deve fazer:

Mudar configurações de criação para produzir bibliotecas de 64 bits

Caso esteja usando uma versão do Unity que oferece suporte a bibliotecas de 64 bits do Android, você pode gerar uma versão de 64 bits do app ajustando as configurações do build. Use o back-end de IL2CPP (em inglês) com scripts. Para configurar seu projeto do Unity para criar arquiteturas de 64 bits, siga estas etapas:

1. Acesse Build Settings e confirme que você está criando para Android. Para fazer isso, confira se o símbolo do Unity está ao lado de Android na seção Platform. 1. Se o símbolo não estiver ao lado da plataforma Android, selecione Android e clique em Switch Platform.

2. Clique em Player settings.

   

3. Navegue até Player Settings Panel > Settings for Android > Other settings > Configuration.

4. Configure o Scripting Backend como IL2CPP.

5. Marque a caixa de seleção Target Architecture > ARM64.

   

6. Continue criando como de costume.

A criação para ARM64 exige que todos os seus recursos sejam criados especificamente para essa plataforma. Siga as orientações do Unity (em inglês) para reduzir o tamanho do APK e use o recurso Android App Bundle para evitar esse aumento de tamanho.

Compliance com vários APKs e 64 bits

Se você estiver usando o suporte a vários APKs do Google Play para publicar seu app, saiba que a conformidade com o requisito de 64 bits é avaliada no nível da versão. No entanto, o requisito de 64 bits não se aplica a APKs ou pacotes de apps que não são distribuídos para dispositivos com o Android 9 Pie ou mais recente.

Se um dos seus APKs estiver marcado como não conforme, mas for uma versão anterior que não pode atender ao requisito, adicione um atributo maxSdkVersion="27" ao elemento uses-sdk no manifesto dele. Dessa forma, o APK não será entregue a dispositivos com o Android 9 Pie ou mais recente e permitirá a conformidade.

Compliance com RenderScript e 64 bits

Caso seu app use o RenderScript e tenha sido criado com uma versão anterior das ferramentas do Android, você poderá ter problemas de conformidade com 64 bits. Com ferramentas de build anteriores à 21.0.0, o compilador pode gerar bitcode em um arquivo .bc externo. Esses arquivos .bc legados não têm mais suporte de arquiteturas de 64 bits, então a presença do arquivo no APK causa o problema de conformidade.

Para resolver o problema, remova todos os arquivos .bc do seu projeto, faça upgrade do ambiente para build-tools-21.0.0 ou uma versão mais recente e defina a renderscriptTargetApi no Android Studio como 21 ou mais recente para instruir o compilador a não emitir mais arquivos .bc. Em seguida, recrie seu app, confira se não há mais arquivos .bc e faça upload para o Play Console.

Testar o app em hardware de 64 bits

A versão de 64 bits do seu app deve oferecer a mesma qualidade e o mesmo conjunto de recursos da versão de 32 bits. Teste seu app para garantir que os usuários dos dispositivos de 64 bits mais recentes tenham uma ótima experiência.

Dispositivos apenas de 64 bits

Sempre que possível, recomendamos testar o app em um ambiente de 64 bits usando uma destas opções:

• Google Pixel com uma imagem de sistema exclusiva para 64 bits
• Android Emulator

Google Pixel com uma imagem de sistema exclusiva para 64 bits

Para facilitar o desenvolvimento e o teste de apps, fornecemos imagens especiais do sistema com um ambiente exclusivo de 64 bits para alguns dispositivos Pixel. Essas imagens de 64 bits foram fornecidas originalmente junto a imagens do sistema padrão de fábrica para versões de pré-lançamento do Android 13 e 14, mas você pode continuar a usá-las para testar a compatibilidade do app com 64 bits.

Usar uma imagem exclusiva para 64 bits

Assim como imagens do sistema de fábrica, é possível instalar uma imagem exclusiva para 64 bits no dispositivo usando a Android Flash Tool ou atualizando o dispositivo manualmente, conforme descrito nas próximas seções.

Atualizar um dispositivo usando a Android Flash Tool

A Android Flash Tool permite atualizar com segurança uma imagem do sistema em um dispositivo Pixel com suporte. A Android Flash Tool funciona com qualquer navegador da Web com suporte para WebUSB, como o Chrome ou o Edge 79+.

A Android Flash Tool orienta você em todas as etapas do processo de atualização do dispositivo. Não é necessário ter ferramentas instaladas, mas é necessário desbloquear o dispositivo e ativar a depuração USB nas Opções do desenvolvedor. Para conferir as instruções completas, consulte a documentação da Android Flash Tool.

Conecte o dispositivo usando um cabo USB. Dependendo do tipo de imagem do sistema que você quer atualizar, acesse a Android Flash Tool usando um dos links abaixo e siga as orientações na tela:

• Imagens do sistema exclusivas para 64 bits do Android 14 (Beta 5.2)

  Selecione o dispositivo que você está tentando atualizar:

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

• Imagens do sistema exclusivas para 64 bits do Android 13 (QPR3 Beta 3.2)

  Selecione o dispositivo que você está tentando atualizar:

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

Atualizar o dispositivo manualmente

Você também pode fazer o download da imagem mais recente do sistema e a instalar manualmente no dispositivo. Consulte a tabela abaixo para fazer o download da imagem do sistema no dispositivo de teste. A atualização manual em um dispositivo é útil caso seja necessário ter controle preciso sobre o ambiente de teste ou caso haja a necessidade reinstalar com frequência, como ao fazer testes automatizados.

Depois de fazer backup dos dados do dispositivo e fazer o download da imagem do sistema correspondente, você pode atualizar a imagem no dispositivo.

É possível voltar para o build público mais recente quando você quiser.

Imagens de fábrica exclusivas para 64 bits no Android 14 (Beta 5.3)

Essas imagens oferecem um ambiente para testar a compatibilidade de apps de 64 bits. As configurações exclusivas para 64 bits estão disponíveis apenas para uso de desenvolvedores.

Imagens de fábrica exclusivas para 64 bits no Android 13 (QPR3 Beta 3.2)

Essas imagens oferecem um ambiente para testar a compatibilidade de apps de 64 bits. As configurações exclusivas para 64 bits estão disponíveis apenas para uso de desenvolvedores.

Voltar para um build público

Você pode usar a Android Flash Tool para atualizar a imagem de fábrica ou fazer o download de uma imagem do sistema com especificações de fábrica na página Imagens de fábrica para dispositivos Nexus e Pixel para atualizar o dispositivo manualmente.

Android Emulator

No Android 12 (nível 31 da API) e versões mais recentes, as imagens do sistema do Android Emulator são exclusivas para 64 bits. Crie um Dispositivo virtual Android (AVD, na sigla em inglês) usando uma imagem do sistema com o Android 12 (nível 31 da API) ou mais recente para acessar um ambiente exclusivo para 64 bits em que você pode testar seus apps.

Outras opções de dispositivos

Se você não tem um desses dispositivos ou não consegue usar o Android Emulator, sua melhor opção é utilizar um dispositivo compatível com 64 bits, como um Google Pixel ou outros dispositivos principais recentes de outros fabricantes.

Instalar e testar o app

A maneira mais fácil de testar seu APK é instalar o app usando o Android Debug Bridge (adb). Na maioria dos casos, você pode fornecer --abi como um parâmetro para indicar quais bibliotecas vão ser instaladas no dispositivo. Isso faz com que o app seja instalado apenas com as bibliotecas de 64 bits.

:: Command Line
# A successful install:
> adb install --abi armeabi-v7a YOUR_APK_FILE.apk
Success

# If your APK does not have the 64-bit libraries:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
adb: failed to install YOUR_APK_FILE.apk: Failure [INSTALL_FAILED_NO_MATCHING_ABIS: Failed to extract native libraries, res=-113]

# If your device does not support 64-bit, an emulator, for example:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
ABI arm64-v8a not supported on this device

Depois de concluir a instalação, teste o app como normalmente faria para garantir que a qualidade seja igual à da versão de 32 bits.

Verificar problemas de compatibilidade conhecidos

Durante o teste, confira se o app tem os problemas descritos a seguir, que afetam apps em 64 bits. Mesmo que o app não dependa das bibliotecas afetadas diretamente, isso pode acontecer com bibliotecas e SDKs de terceiros nas dependências do app.

SoLoader

Se você estiver usando o SDK do carregador de código nativo SoLoader, atualize-o para a versão 0.10.4 ou mais recente. Se o app usa SDKs que dependem do SoLoader, também atualize os SDKs afetados para a versão estável mais recente.

O SoLoader v0.9.0 e versões anteriores presumem que bibliotecas do sistema estejam presentes em /vendor/lib:/system/lib. Esse bug não aparece em dispositivos como o Pixel 7, em que o caminho existe, mas essa suposição causa falhas em dispositivos que só têm bibliotecas do sistema em /vendor/lib64:/system/lib64.

Para saber mais sobre como corrigir esse e outros problemas causados pelo SoLoader, consulte a resposta correspondente na Central de Ajuda do Google.

OpenSSL

Se você está usando a biblioteca OpenSSL, atualize para a OpenSSL 1.1.1i ou versão mais recente. Se o app usa SDKs com comunicação por HTTPS ou outros SDKs que dependem do OpenSSL, também atualize o SDK que usa uma versão mais nova do OpenSSL para a versão mais recente. Entre em contato com o provedor do SDK se não houver uma versão disponível.

ARMv8.3 PAC permite a integridade do fluxo de controle assistido por hardware ao autenticar ponteiros no momento da execução. As versões anteriores do OpenSSL usam essas capabilities incorretamente, causando falhas na execução em todos os dispositivos com processadores baseados em ARMv8.3a e mais recentes.

Para saber mais sobre como corrigir esse e outros problemas causados pelo OpenSSL, consulte a resposta correspondente na Central de Ajuda do Google.

BTI

O ARMv8.5 e versões mais recentes usam instruções de destino de ramificação (BTIs, na sigla em inglês) para ajudar na proteção contra ataques JOP. Versões anteriores de SDKs de ofuscação que se ramificam em deslocamentos aleatórios de bibliotecas criadas com BTI podem causar falhas no app. Como as instruções são codificadas como HINTs, esse bug não é observável em dispositivos sem suporte à BTI.

Publicar

Quando você achar que seu app está pronto, publique-o normalmente. Como sempre, continue seguindo as práticas recomendadas para implantar o app. Recomendamos usar as faixas de teste fechado para fazer o lançamento para um número limitado de usuários e garantir a consistência da qualidade do app.

Assim como ao implementar uma atualização importante, teste o app completamente em dispositivos compatíveis com 64 bits antes da publicação para um público maior.