Suporte tamanhos de páginas de 16 KB

Historicamente, o Android só ofereceu suporte a tamanhos de página de memória de 4 KB, o que otimizou o desempenho da memória do sistema para a quantidade média de memória total que os dispositivos Android normalmente tinham. A partir do Android 15, o AOSP oferece suporte a dispositivos configurados para usar um tamanho de página de 16 KB (dispositivos de 16 KB). Se o app usar alguma biblioteca do NDK, seja direta ou indiretamente por um SDK, será necessário recriar o app para que ele funcione nesses dispositivos de 16 KB.

À medida que os fabricantes de dispositivos continuam criando dispositivos com quantidades maiores de memória física (RAM), muitos deles vão adotar tamanhos de página de 16 KB (e eventualmente maiores) para otimizar o desempenho do dispositivo. Ao adicionar suporte para dispositivos com tamanho de página de 16 KB, você permite que o app seja executado nesses dispositivos e aproveite as melhorias de desempenho associadas. Sem recompilação, os apps não vão funcionar em dispositivos de 16 KB em versões futuras do Android.

Para ajudar você a adicionar suporte ao app, fornecemos orientações sobre como verificar se o app foi afetado, como recompilar o app (se aplicável) e como testar o app em um ambiente de 16 KB usando emuladores (incluindo imagens do sistema Android 15 para o Android Emulator).

Requisito de compatibilidade do Google Play

Para garantir que a sua app funciona corretamente nas versões mais recentes do Android, todas as apps que segmentam o Android 15 (nível da API 35) e superior têm de ser compatíveis com tamanhos de páginas de memória de 16 KB em dispositivos de 64 bits no Google Play. A partir de 1 de fevereiro de 2027, se as atualizações da sua app não forem compatíveis com tamanhos de páginas de memória de 16 KB, não vai poder lançar essas atualizações.

Aviso da Google Play Console de que as atualizações de apps têm de ser compatíveis com tamanhos de páginas de memória de 16 KB até 1 de fevereiro de 2027
Figura 1. Aviso de compatibilidade da Google Play Console.

Vantagens e ganhos de desempenho

Os dispositivos configurados com tamanhos de página de 16 KB usam um pouco mais de memória em média, mas também têm várias melhorias de desempenho para o sistema e os apps:

  • Tempos de inicialização do app mais rápidos enquanto o sistema está sob pressão de memória: 3,16% mais baixos em média, com melhorias mais significativas (até 30%) em alguns apps testados.
  • Redução do consumo de energia durante o lançamento do app: redução média de 4,56%
  • Lançamento mais rápido da câmera: 4,48% mais rápido em média e 6,60% mais rápido em média
  • Tempo de inicialização do sistema melhorado: melhoria de 8% (aproximadamente 950 milissegundos) em média

Essas melhorias são baseadas nos testes iniciais, e os resultados em dispositivos reais provavelmente serão diferentes. Forneceremos análises adicionais de ganhos em potencial para apps à medida que continuarmos nossos testes.

Verifique se a sua app é afetada

Se o app usar código nativo, recompile o app com suporte para dispositivos de 16 KB. Se você não tiver certeza se o app usa código nativo, use o APK Analyzer para identificar se há código nativo e verifique o alinhamento dos segmentos ELF de bibliotecas compartilhadas encontradas. O Android Studio também oferece recursos que ajudam a detectar automaticamente problemas de alinhamento.

Se o app usa apenas código escrito na linguagem de programação Java ou Kotlin, incluindo bibliotecas ou SDKs, ele já oferece suporte a dispositivos de 16 KB. No entanto, recomendamos que você teste o app em um ambiente de 16 KB para verificar se não há regressões inesperadas no comportamento do app.

A sua app usa código nativo?

A sua app usa código nativo se alguma das seguintes condições se aplicar:

  • A sua app usa código C/C++ (nativo). Se a sua app usar o Android NDK, usa código nativo.
  • A sua app tem links para bibliotecas ou dependências nativas de terceiros (como SDKs) que as usam.
  • A sua app é criada por um criador de apps de terceiros que usa bibliotecas nativas no dispositivo.

Identifique bibliotecas nativas com o APK Analyzer

O APK Analyzer é uma ferramenta que lhe permite avaliar vários aspetos de um APK criado. Para verificar se a sua app usa código nativo (independentemente de ser compatível com 16 KB):

  1. Abra o Android Studio e, de seguida, clique em File > Open e escolha um projeto.

  2. Na barra de menu, clique em Build > Analyze APK...

    Opção do menu de compilação do Studio para iniciar o APK Analyzer

  3. Escolha o APK que quer analisar.

  4. Procure na pasta lib, que aloja ficheiros de objetos partilhados (.so), se existirem. Se existirem ficheiros de objetos partilhados, a sua app usa código nativo. A coluna Alignment apresenta mensagens de aviso para todos os ficheiros que tenham problemas de alinhamento. Se não existirem ficheiros de objetos partilhados ou não existir uma pasta lib, a sua app não usa código nativo.

    Vista do analisador de APK a mostrar que existem ficheiros de objetos partilhados

Detete problemas de alinhamento com verificações automáticas

O Android Studio avisa-o proativamente se as suas bibliotecas ou APKs pré-criados não forem compatíveis com 16 KB. Use a ferramenta APK Analyzer para rever as bibliotecas que têm de ser atualizadas ou se são necessárias alterações ao código.

<figure>
  <img src="/images/guide/practices/studio-align-warnings.png"
       class="no-filter" width="300"
       alt="Studio warning notifications about alignment issues in a project">
</figure>

O Lint no Android Studio também realça bibliotecas nativas que não estão alinhadas com 16 KB.

<figure>
  <img src="/images/guide/practices/studio-align-lint.png"
       class="no-filter"
       alt="Studio linter warning about a non-aligned native library">
</figure>

Verifique o alinhamento de segmentos ELF para bibliotecas partilhadas

Para todas as bibliotecas partilhadas, valide se os segmentos ELF das bibliotecas partilhadas estão alinhados corretamente com o alinhamento ELF de 16 KB. Se estiver a desenvolver no Linux ou macOS, pode usar o script check_elf_alignment.sh conforme descrito na secção seguinte. Também pode usar as ferramentas de linha de comandos diretamente.

Use o script check_elf_alignment.sh (Linux ou macOS)

Siga estes passos para verificar o alinhamento de segmentos ELF com o script check_elf_alignment.sh:

  1. Guarde o script check_elf_alignment.sh num ficheiro.

  2. Execute o script no ficheiro APK da sua app:

    check_elf_alignment.sh APK_NAME.apk

    O script devolve ALIGNED ou UNALIGNED para todas as arm64-v8a bibliotecas partilhadas.

  3. Se alguma biblioteca partilhada arm64-v8a ou x86_64 estiver UNALIGNED, tem de atualizar a embalagem dessas bibliotecas, depois recompilar a app e testá-la novamente seguindo os passos nesta secção.

Use ferramentas de linha de comandos diretamente

Siga estes passos para verificar o alinhamento de segmentos ELF com ferramentas de linha de comandos diretamente:

  1. Certifique-se de que a versão 35.0.0 ou superior das Android SDK Build-Tools e o Android NDK estão instalados com o SDK Manager no Android Studio ou sdkmanager ferramenta de linha de comandos.

  2. Extraia o ficheiro APK da sua app:

    Linux ou macOS

    unzip APK_NAME.apk -d /tmp/my_apk_out

    Windows (PowerShell)

    Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out

  3. No diretório temporário para o qual extraiu o ficheiro APK, verifique o conteúdo do diretório lib para ver se existem ficheiros de objetos partilhados (.so). Estes são os mesmos ficheiros de objetos partilhados que viu quando identificou bibliotecas nativas com o APK Analyzer. Execute o seguinte comando em cada ficheiro de objeto partilhado:

    Linux ou macOS

    SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"

    Em que SDK_ROOT_LOCATION é o caminho para o diretório onde instalou o SDK do Android, SHARED_OBJECT_FILE é o nome do ficheiro de objeto partilhado que está a verificar e NDK_VERSION é a versão do Android NDK que tem instalada (por exemplo, 28.0.12433566). O resultado tem um aspeto semelhante ao seguinte para cada ficheiro que verificar:

    LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14

  4. Verifique as linhas de resultado para garantir que os segmentos de carregamento não têm valores inferiores a 2**14. Se algum segmento de carregamento for 2**13, 2**12, ou valores inferiores, tem de atualizar a embalagem dessas bibliotecas, depois recompilar a app e testá-la novamente seguindo os passos nesta secção.

  5. Em seguida, execute a ferramenta de linha de comandos zipalign no ficheiro APK da sua app:

    Linux ou macOS

    SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk

    Em que SDK_ROOT_LOCATION é o caminho para o diretório onde instalou o SDK do Android e APK_NAME é o nome do ficheiro APK da sua app. A última linha do resultado indica "Verification successful" se todas as bibliotecas partilhadas estiverem alinhadas corretamente.

    Se a validação falhar, algumas bibliotecas partilhadas têm de ser realinhadas. Por isso, tem de atualizar a embalagem dessas bibliotecas, depois recompilar a app e testá-la novamente seguindo os passos nesta secção.

Verifique a sinalização de segurança RELRO

Para mitigar as vulnerabilidades de segurança, os linkers modernos usam a sinalização Relocation Read-Only (RELRO) para tornar as secções de realocação do ficheiro de objeto partilhado apenas de leitura após o carregamento. A combinação de uma secção com a RELRO ativada com uma secção sem a RELRO ativada (de outro ficheiro de objeto) na mesma página provoca uma falha de sistema numa app.

Execute o seguinte comando em cada ficheiro de objeto partilhado (Linux ou macOS):

SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-readelf -l SHARED_OBJECT_FILE.so | grep RELRO

Verifique o resultado do comando para garantir que a string GNU_RELRO é impressa, o que confirma que o ficheiro .so tem a RELRO ativada.

Crie a sua app com compatibilidade com dispositivos de 16 KB

Se a sua app usar código nativo, conclua os passos descritos nas secções seguintes para se certificar de que a app é compatível com dispositivos de 16 KB:

  1. Atualize a embalagem das bibliotecas partilhadas
  2. Compile a sua app com o alinhamento ELF de 16 KB
  3. Corrija o código e resolva problemas de runtime
  4. Verifique se os SDKs são compatíveis com 16 KB

Atualize a embalagem das bibliotecas partilhadas

Atualize para a versão 8.5.1 ou superior do AGP e use bibliotecas partilhadas não comprimidas.

Use a bundletool para validar o alinhamento zip

Para ver o alinhamento do seu pacote, use:

bundletool dump config --bundle=<my .aab>  | grep alignment

Se vir PAGE_ALIGNMENT_16K, sabe que o seu pacote pede um alinhamento zip de 16 KB. Se vir PAGE_ALIGNMENT_4K, isto indica que o APK criado a partir deste AAB tem ficheiros ` .so` alinhados de 4 KB no ficheiro zip.

Versão 8.5.1 ou superior do AGP

Os dispositivos de 16 KB requerem apps que são enviadas com bibliotecas partilhadas não comprimidas para as alinhar num limite alinhado zip de 16 KB. Para o fazer, tem de atualizar para a versão 8.5.1 ou superior do Android Gradle Plugin (AGP). Consulte a secção Assistente de atualização do plugin do Android para o Gradle para ver detalhes sobre o processo de atualização.

Versão 8.5 ou inferior do AGP

Se não conseguir atualizar o AGP para a versão 8.5.1 ou superior, a alternativa é mudar para a utilização de bibliotecas partilhadas comprimidas. Atualize a configuração do Gradle para que o Gradle comprima as bibliotecas partilhadas ao embalar a app para evitar problemas de instalação da app com bibliotecas partilhadas não alinhadas.

Descontraído

No ficheiro build.gradle, adicione a seguinte opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

Kotlin

No ficheiro build.gradle.kts, adicione a seguinte opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}
Versão 8.0 ou inferior do AGP

Se estiver a usar uma versão do AGP igual ou inferior a 8.0, também tem de desativar a opção de biblioteca nativa não comprimida para app bundles no ficheiro gradle.properties:

android.bundle.enableUncompressedNativeLibs=false

Compile a sua app com o alinhamento ELF de 16 KB

Os dispositivos de 16 KB requerem que os segmentos ELF das bibliotecas partilhadas estejam alinhados corretamente com o alinhamento ELF de 16 KB para que a sua app seja executada.

Para programadores de jogos, se o seu jogo for executado no motor de jogos Unity, consulte o guia do Unity. Se o seu jogo for executado no motor de jogos Unreal, consulte o guia do Unreal. Para motores de jogos nativos, continue com este guia.

Para compilar a sua app com o alinhamento ELF de 16 KB, conclua os passos numa das secções seguintes, consoante a versão do Android NDK que está a usar.

Android NDK r28 e superior

O NDK versão r28 e superior compila por predefinição com um alinhamento de 16 KB.

Android NDK r27 e inferior

Para ser compatível com a compilação de bibliotecas partilhadas alinhadas de 16 KB com o Android NDK versão r27 ou inferior, use as seguintes sinalizações do linker:

-Wl,-z,max-page-size=16384
-Wl,-z,common-page-size=16384

Veja como atualizar os ficheiros de configuração do sistema de compilação:

ndk-build

Se estiver a usar o ndk-build, atualize o Android.mk para ativar o alinhamento ELF de 16 KB:

LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384 -Wl,-z,common-page-size=16384

CMake

Se estiver a usar o CMake, atualize o CMakeLists.txt para ativar o alinhamento ELF de 16 KB:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE
    "-Wl,-z,max-page-size=16384"
    "-Wl,-z,common-page-size=16384"
)

Corrija o código e resolva problemas de runtime

Mesmo que a sua app esteja alinhada com 16 KB, pode deparar-se com erros se determinados locais no código assumirem que um dispositivo está a usar um tamanho de página específico. Para evitar esta situação, conclua os seguintes passos:

  1. Remova todas as dependências codificadas que referenciem a PAGE_SIZE constante ou instâncias na lógica do código que assumam que o tamanho da página de um dispositivo é de 4 KB (4096).

    Use getpagesize() ou sysconf(_SC_PAGESIZE) em alternativa.

  2. Procure utilizações de mmap() e outras APIs que requerem argumentos alinhados com a página e substitua-os por alternativas, se necessário.

Em alguns casos, se a sua app usar PAGE_SIZE como um valor conveniente que não está associado ao tamanho da página subjacente, isto não faz com que a app deixe de funcionar quando é usada no modo de 16 KB. No entanto, se este valor for transmitido ao kernel com mmap sem MAP_FIXED, o kernel continua a usar uma página inteira, o que desperdiça alguma memória. Por estes motivos, PAGE_SIZE não está definido quando o modo de 16 KB está ativado no NDK r27 e superior.

Se a sua app usar PAGE_SIZE desta forma e nunca transmitir diretamente este valor ao kernel, em vez de usar PAGE_SIZE, crie uma nova variável com um novo nome para refletir que é usada para outros fins e não reflete uma página de memória real.

Verifique se os SDKs são compatíveis com 16 KB

Muitos SDKs são compatíveis com tamanhos de páginas de 16 KB, especialmente se os criar ou obter pré-criados recentes. No entanto, uma vez que alguns pré-criados ou versões de SDK não são compatíveis com 16 KB, deve consultar o Website de cada fornecedor de SDK para determinar a versão a usar com 16 KB.

Teste a sua app num ambiente de 16 KB

Depois de criar a sua app com compatibilidade com dispositivos de 16 KB, deve testá-la num ambiente de 16 KB para ver se a app tem regressões. Para o fazer, siga estes passos:

  1. Configure o SDK do Android 15 ou superior.

  2. Configure um dos seguintes ambientes de teste:

  3. Inicie o dispositivo de teste e, de seguida, execute o seguinte comando para validar se está a usar um ambiente de 16 KB:

    adb shell getconf PAGE_SIZE

    O comando deve devolver um valor de 16384.

  4. Execute o seguinte zipalign comando para validar se a sua app está alinhada com 16 KB, em que APK_NAME é o nome do ficheiro APK da sua app:

    zipalign -c -P 16 -v 4 APK_NAME.apk

  5. Teste exaustivamente a sua app, concentrando-se em todas as áreas que possam ser afetadas pela alteração de instâncias de código que referenciam tamanhos de páginas específicos.

Configure o emulador do Android com uma imagem do sistema baseada em 16 KB

Para configurar um ambiente de 16 KB com o emulador do Android, siga estes passos:

  1. No Android Studio, clique em Tools > SDK Manager.

  2. No separador SDK Platforms , selecione Show Package Details e, de seguida, expanda a secção Android VanillaIceCream ou superior e selecione uma ou ambas as seguintes imagens do sistema do emulador, consoante os dispositivos virtuais que quer criar:

    • Google APIs Experimental 16 KB Page Size ARM 64 v8a System Image
    • Google APIs Experimental 16 KB Page Size Intel x86_64 Atom System Image
    Transfira imagens do sistema do emulador de 16 KB através do SDK Manager no Android Studio

  3. Clique em Apply > OK para transferir as imagens do sistema que selecionou.

  4. Siga os passos para configurar um dispositivo virtual para o Android 15 e, quando lhe for pedido que selecione uma imagem do sistema, selecione a imagem do sistema de 16 KB que transferiu. Se não for recomendado automaticamente, pode encontrar a imagem do sistema de 16 KB no separador Other Images.

    Encontre a imagem do emulador de 16 KB no separador Outras imagens

Inicie o emulador

Depois de concluir a configuração do emulador do Android e dos dispositivos virtuais, inicie o emulador no menu do dispositivo de destino ou na linha de comandos.

Ativar o modo 16 KB em um dispositivo usando as opções do desenvolvedor

Ative a opção de desenvolvedor Inicializar com tamanho de página de 16 KB para inicializar um dispositivo no modo de 16 KB.

Nas versões QPR do Android 15, é possível usar a opção do desenvolvedor disponível em alguns dispositivos para inicializar o dispositivo no modo de 16 KB e realizar testes no dispositivo. Antes de usar a opção do desenvolvedor, acesse Configurações > Sistema > Atualizações de software e aplique as atualizações disponíveis.

Essa opção para desenvolvedores está disponível nos seguintes dispositivos:

  • Pixel 8 e 8 Pro (com Android 15 QPR1 ou versões mais recentes)

  • Pixel 8a (com Android 15 QPR1 ou versões mais recentes)

  • Pixel 9, 9 Pro e 9 Pro XL (com Android 15 QPR2 ou versões mais recentes)

  • Pixel 9a (com Android 16 ou versões mais recentes)

Modo de retrocompatibilidade de 16 KB

Aviso no modo de compatibilidade com o tamanho da página

Aviso no modo de compatibilidade com o tamanho da página

A opção de retrocompatibilidade de 16 KB está disponível quando um dispositivo está a ser executado com um kernel de 16 KB. O gestor de pacotes executa uma app no modo de retrocompatibilidade de 16 KB quando são cumpridas as seguintes condições:

  • Se a app tiver ficheiros ELF (com uma extensão .so) com um alinhamento de segmento LOAD de 4 KB.
  • Se o APK zipado tiver ficheiros ELF não comprimidos que estejam alinhados zip de 4 KB.

Se o gestor de pacotes tiver ativado o modo de retrocompatibilidade de 16 KB para uma app, a app apresenta um aviso quando é iniciada pela primeira vez a indicar que está a ser executada no modo de retrocompatibilidade de 16 KB.

O modo de retrocompatibilidade de 16 KB permite que algumas apps funcionem, mas, para uma melhor fiabilidade e estabilidade, as apps devem continuar a estar alinhadas com 16 KB.

Na página de informações da app, em Advanced, ative ou desative a definição Run app with page size compat mode para ativar ou desativar o modo de retrocompatibilidade de 16 KB para uma app específica. Esta definição só é visível quando o dispositivo está a ser executado com um tamanho de página de 16 KB.

Definição do modo de compatibilidade com o tamanho da página

Definição do modo de compatibilidade com o tamanho da página

Para forçar a retrocompatibilidade de 16 KB para todas as apps no dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled true
adb shell setprop pm.16kb.app_compat.disabled false

Para forçar a desativação da retrocompatibilidade de 16 KB para todas as apps no dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled false
adb shell setprop pm.16kb.app_compat.disabled true

No Android 17, também pode forçar a desativação da retrocompatibilidade de 16 KB para todas as apps e fazer com que qualquer binário incompatível seja abortado imediatamente:

    adb shell setprop bionic.linker.16kb.app_compat.enabled fatal
    adb shell setprop pm.16kb.app_compat.disabled true

Defina a propriedade android:pageSizeCompat como ativada ou desativada para ativar ou desativar o modo de retrocompatibilidade para uma app específica no respetivo AndroidManifest.xml. Quando esta propriedade está definida, a app não apresenta avisos do modo de retrocompatibilidade quando é iniciada.