Admitir tamaños de página de 16 kB

Históricamente, Android solo admitió tamaños de página de memoria de 4 KB, lo que optimizó el rendimiento de la memoria del sistema para la cantidad promedio de memoria total que suelen tener los dispositivos Android. A partir de Android 15, el AOSP admite dispositivos configurados para usar un tamaño de página de 16 KB (dispositivos de 16 KB). Si tu app usa alguna biblioteca del NDK, ya sea directamente o a través de un SDK, deberás volver a compilarla para que funcione en estos dispositivos de 16 KB.

A medida que los fabricantes de dispositivos sigan creando dispositivos con mayores cantidades de memoria física (RAM), muchos de estos dispositivos adoptarán tamaños de página de 16 KB (y, con el tiempo, incluso mayores) para optimizar el rendimiento del dispositivo. Agregar compatibilidad con dispositivos con tamaño de página de 16 KB permite que tu app se ejecute en estos dispositivos y se beneficie de las mejoras de rendimiento asociadas. Sin recompilación, las apps no funcionarán en dispositivos de 16 KB en futuras versiones de Android.

Para ayudarte a agregar compatibilidad con tu app, te proporcionamos orientación sobre cómo comprobar si tu app se ve afectada, cómo volver a compilar tu app (si corresponde) y cómo probar tu app en un entorno de 16 KB con emuladores (incluidas las imágenes del sistema de Android 15 para Android Emulator).

Requisito de compatibilidad con Google Play

Para asegurarte de que tu aplicación funcione correctamente en las versiones más recientes de Android, todas las aplicaciones orientadas a Android 15 (nivel de API 35) y versiones posteriores deben admitir tamaños de página de memoria de 16 KB en dispositivos de 64 bits en Google Play. A partir del 1 de febrero del 2027, si las actualizaciones de tu aplicación no admiten tamaños de página de memoria de 16 KB, no podrás lanzarlas.

Advertencia de Google Play Console de que las actualizaciones de las aplicaciones deben admitir tamaños de página de memoria de 16 KB antes del 1 de febrero del 2027
Imagen 1. Advertencia de compatibilidad de Google Play Console.

Ventajas y mejoras de rendimiento

Los dispositivos configurados con tamaños de página de 16 KB usan un poco más de memoria en promedio, pero también obtienen varias mejoras de rendimiento para el sistema y las apps:

  • Tiempos de inicio de la app más bajos mientras el sistema está bajo presión de memoria: un 3.16% más bajo en promedio, con mejoras más significativas (hasta un 30%) para algunas apps que probamos
  • Menor consumo de energía durante el lanzamiento de la app: Reducción promedio del 4.56%
  • Inicio más rápido de la cámara: Inicios en caliente un 4.48% más rápidos en promedio y, en promedio, un 6.60% más rápidos en frío
  • Mejor tiempo de inicio del sistema: se mejoró en un 8% (aproximadamente 950 milisegundos) en promedio.

Estas mejoras se basan en nuestras pruebas iniciales, y es probable que los resultados en los dispositivos reales difieran. Proporcionaremos análisis adicionales de posibles ganancias para las apps a medida que continuemos con las pruebas.

Comprobar si tu aplicación se ve afectada

Si tu app usa código nativo, debes recompilarla para que sea compatible con dispositivos de 16 KB. Si no sabes con seguridad si tu app usa código nativo, puedes usar el Analizador de APK para identificar si hay código nativo presente y, luego, verificar la alineación de los segmentos ELF de las bibliotecas compartidas que encuentres. Android Studio también proporciona funciones que te ayudan a detectar automáticamente problemas de alineación.

Si tu app solo usa código escrito en el lenguaje de programación Java o en Kotlin, incluidas todas las bibliotecas o SDKs, ya es compatible con dispositivos de 16 KB. Sin embargo, te recomendamos que pruebes tu app en un entorno de 16 KB para verificar que no haya regresiones inesperadas en el comportamiento de la app.

¿Su aplicación usa código nativo?

Su aplicación hace uso de código nativo si se cumple alguna de las siguientes condiciones:

  • Su aplicación usa código C/C++ (nativo). Si su aplicación usa el Android NDK, entonces usa código nativo.
  • Su aplicación enlaza con bibliotecas o dependencias nativas de terceros (como SDKs) que las usan.
  • Su aplicación está compilada por un generador de aplicaciones de terceros que utiliza bibliotecas nativas en el dispositivo.

Identificar bibliotecas nativas con el Analizador de APK

Analizador de APK es una herramienta que le permite evaluar varios aspectos de un APK compilado. Para comprobar si su aplicación usa código nativo (independientemente de si es compatible con 16 KB):

  1. Abra Android Studio, haga clic en Archivo > Abrir y elija cualquier proyecto.
  2. En la barra de menús, haga clic en Compilación > Analizar APK...

    Opción del menú Compilación de Studio para iniciar Analizador de APK
  3. Elija el APK que quiera analizar.

  4. Busque en la carpeta lib, que contiene archivos de objetos compartidos (.so) si los hay. Si hay archivos de objetos compartidos, su aplicación usa código nativo. La columna Alineación muestra mensajes de advertencia para los archivos que tengan problemas de alineación. Si no hay archivos de objetos compartidos o no hay ninguna carpeta lib, su aplicación no usa código nativo.

    Vista del Analizador de APK que muestra que hay archivos de objetos compartidos

Detectar problemas de alineación con comprobaciones automáticas

Android Studio le avisa de forma proactiva si sus bibliotecas o APKs precompilados no cumplen el requisito de 16 KB. Use la herramienta APK Analyzer para revisar qué bibliotecas deben actualizarse o si se requieren cambios en el 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>

Lint en Android Studio también destaca las bibliotecas nativas que no están alineadas con 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>

Comprobar la alineación de los segmentos ELF de las bibliotecas compartidas

En el caso de las bibliotecas compartidas, compruebe que los segmentos ELF de las bibliotecas compartidas estén alineados correctamente mediante la alineación ELF de 16 KB. Si está desarrollando en Linux o macOS, puede usar la secuencia de comandos check_elf_alignment.sh, tal como se describe en la siguiente sección. También puede usar las herramientas de línea de comandos directamente.

Usar la secuencia de comandos check_elf_alignment.sh (Linux o macOS)

Siga estos pasos para comprobar la alineación de los segmentos ELF con la secuencia de comandos check_elf_alignment.sh:

  1. Guarde la secuencia de comandos check_elf_alignment.sh en un archivo.

  2. Ejecute la secuencia de comandos en el archivo APK de su aplicación:

    check_elf_alignment.sh APK_NAME.apk
    

    La secuencia de comandos genera ALIGNED o UNALIGNED para todas las arm64-v8a bibliotecas compartidas.

  3. Si alguna biblioteca compartida arm64-v8a o x86_64 está UNALIGNED, deberá actualizar el empaquetado de esas bibliotecas, luego volver a compilar su aplicación y volver a probarla siguiendo los pasos de esta sección.

Usar herramientas de línea de comandos directamente

Siga estos pasos para comprobar la alineación de los segmentos ELF con herramientas de línea de comandos directamente:

  1. Asegúrese de que tanto las herramientas de compilación del SDK para Android, versión 35.0.0 o posterior, como el Android NDK estén instalados mediante el Gestor de SDK en Android Studio o sdkmanager herramienta de línea de comandos.
  2. Extraiga el archivo APK de su aplicación:

    Linux o macOS

    unzip APK_NAME.apk -d /tmp/my_apk_out
    

    Windows (PowerShell)

    Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
    
  3. En el directorio temporal en el que haya extraído el archivo APK, compruebe el contenido del directorio lib para ver si hay archivos de objetos compartidos (.so). Estos son los mismos archivos de objetos compartidos que habría visto al identificar bibliotecas nativas con el Analizador de APK. Ejecute el siguiente comando en cada archivo de objetos compartidos:

    Linux o 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"
    

    Donde SDK_ROOT_LOCATION es la ruta al directorio en el que ha instalado el SDK para Android, SHARED_OBJECT_FILE es el nombre del archivo de objetos compartidos que está comprobando y NDK_VERSION es la versión de Android NDK que tiene instalada (por ejemplo, 28.0.12433566). El resultado será similar al siguiente para cada archivo que compruebe:

    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. Compruebe las líneas de salida para asegurarse de que los segmentos de carga no tengan valores inferiores a 2**14. Si algún segmento de carga tiene valores 2**13, 2**12 o inferiores , deberá actualizar el empaquetado de esas bibliotecas, luego volver a compilar su aplicación y volver a probarla siguiendo los pasos de esta sección.

  5. A continuación, ejecute la herramienta de línea de comandos zipalign en el archivo APK de su aplicación:

    Linux o 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
    

    Donde SDK_ROOT_LOCATION es la ruta al directorio en el que ha instalado el SDK para Android y APK_NAME es el nombre del archivo APK de su aplicación. La última línea del resultado indicará "Verification successful" (Verificación correcta) si todas las bibliotecas compartidas están alineadas correctamente.

    Si la verificación falla, algunas bibliotecas compartidas deben volver a alinearse, por lo que deberá actualizar el empaquetado de esas bibliotecas, luego volver a compilar su aplicación y volver a probarla siguiendo los pasos de esta sección.

Comprobar el indicador de seguridad RELRO

Para mitigar los exploits de seguridad, los enlazadores modernos usan el indicador Relocation Read-Only (RELRO) para que las secciones de reubicación del archivo de objetos compartidos sean de solo lectura después de la carga. Si se combina una sección habilitada para RELRO con una sección no habilitada para RELRO (de otro archivo de objetos) en la misma página, la aplicación se bloquea.

Ejecute el siguiente comando en cada archivo de objetos compartidos (Linux o 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

Compruebe el resultado del comando para asegurarse de que se imprima la cadena GNU_RELRO, lo que confirma que el archivo .so está habilitado para RELRO.

Compilar su aplicación para que sea compatible con dispositivos de 16 KB

Si su aplicación usa código nativo, siga los pasos que se indican en las siguientes secciones para asegurarse de que su aplicación sea compatible con dispositivos de 16 KB:

  1. Actualizar el empaquetado de sus bibliotecas compartidas
  2. Compilar su aplicación con la alineación ELF de 16 KB
  3. Corregir el código y resolver problemas de tiempo de ejecución
  4. Comprobar si los SDKs son compatibles con 16 KB

Actualizar el empaquetado de sus bibliotecas compartidas

Actualice a la versión 8.5.1 o posterior de AGP y use bibliotecas compartidas sin comprimir.

Usar bundletool para verificar la alineación de ZIP

Para ver la alineación de su paquete, use lo siguiente:

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

Si ve PAGE_ALIGNMENT_16K, sabrá que su paquete solicita la alineación de ZIP de 16 KB. Si ve PAGE_ALIGNMENT_4K, esto indica que el APK compilado a partir de este AAB debe tener archivos .so alineados de 4 KB en el archivo ZIP.

AGP 8.5.1 o posterior

Los dispositivos de 16 KB requieren que las aplicaciones que se envían con bibliotecas compartidas sin comprimir las alineen en un límite alineado de ZIP de 16 KB. Para ello, debe actualizar a la versión 8.5.1 o posterior del complemento de Android para Gradle (AGP). Consulte la sección Asistente de actualización del complemento de Android para Gradle para obtener más información sobre el proceso de actualización.

AGP 8.5 o anterior

Si no puede actualizar AGP a la versión 8.5.1 o posterior, la alternativa es usar bibliotecas compartidas comprimidas. Actualice su configuración de Gradle para que Gradle comprima sus bibliotecas compartidas al empaquetar su aplicación y evitar problemas de instalación de la aplicación con bibliotecas compartidas no alineadas.

Estilosa

En su archivo build.gradle, añada la siguiente opción:

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

Kotlin

En su archivo build.gradle.kts, añada la siguiente opción:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}
AGP 8.0 o anterior

Si usa una versión de AGP igual o inferior a la 8.0, también debe inhabilitar la opción de biblioteca nativa sin comprimir para los Android App Bundles en su archivo gradle.properties:

android.bundle.enableUncompressedNativeLibs=false

Compilar su aplicación con la alineación ELF de 16 KB

Para que su aplicación se ejecute, los dispositivos de 16 KB requieren que los segmentos ELF de las bibliotecas compartidas estén alineados correctamente mediante la alineación ELF de 16 KB.

En el caso de los desarrolladores de juegos, si su juego se ejecuta sobre el motor de juegos Unity, consulte la guía de Unity. Si su juego se ejecuta sobre el motor de juegos Unreal, consulte la guía de Unreal. En el caso de los motores de juegos nativos, siga esta guía.

Para compilar su aplicación con la alineación ELF de 16 KB, siga los pasos de una de las siguientes secciones en función de la versión de Android NDK que esté usando.

Android NDK r28 y versiones posteriores

NDK r28 y versiones posteriores se compilan con la alineación de 16 KB de forma predeterminada.

Android NDK r27 y versiones anteriores

Para admitir la compilación de bibliotecas compartidas alineadas de 16 KB con Android NDK r27 o versiones anteriores, use los siguientes indicadores de enlazador:

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

A continuación, se indica cómo actualizar los archivos de configuración del sistema de compilación:

ndk-build

Si usa ndk-build, actualice su Android.mk para habilitar la alineación ELF de 16 KB:

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

CMake

Si usa CMake, actualice su CMakeLists.txt para habilitar la alineación ELF de 16 KB:

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

Corregir el código y resolver problemas de tiempo de ejecución

Aunque su aplicación esté alineada con 16 KB, puede que se produzcan errores si en su código se da por hecho que un dispositivo usa un tamaño de página específico. Para evitarlo, siga estos pasos:

  1. Elimine las dependencias codificadas que hagan referencia a la PAGE_SIZE constante o a las instancias de su lógica de código que den por hecho que el tamaño de página de un dispositivo es de 4 KB (4096).

    Use getpagesize() o sysconf(_SC_PAGESIZE) en su lugar.

  2. Busque los usos de mmap() y otras APIs que requieran argumentos alineados de página y sustitúyalos por alternativas cuando sea necesario.

En algunos casos, si su aplicación usa PAGE_SIZE como un valor conveniente que no está vinculado al tamaño de página subyacente, esto no hará que su aplicación deje de funcionar cuando se use en el modo de 16 KB. Sin embargo, si este valor se pasa al kernel con mmap sin MAP_FIXED, el kernel sigue usando una página completa, lo que desperdicia memoria. Por estos motivos, PAGE_SIZE no está definido cuando el modo de 16 KB está habilitado en NDK r27 y versiones posteriores.

Si su aplicación usa PAGE_SIZE de esta manera y nunca pasa directamente este valor al kernel, en lugar de usar PAGE_SIZE, cree una variable nueva con un nombre nuevo para reflejar que se usa para otros fines y no refleja una página de memoria real.

Comprobar si los SDKs son compatibles con 16 KB

Muchos SDKs son compatibles con tamaños de página de 16 KB, sobre todo si los compila usted mismo o si obtiene precompilados recientes. Sin embargo, como algunos precompilados de SDKs o versiones de SDKs no son compatibles con 16 KB, debe consultar el sitio web de cada proveedor de SDKs para determinar qué versión usar con 16 KB.

Probar su aplicación en un entorno de 16 KB

Después de compilar su aplicación para que sea compatible con dispositivos de 16 KB, le recomendamos que la pruebe en un entorno de 16 KB para ver si experimenta alguna regresión. Para ello, siga estos pasos:

  1. Configure el SDK de Android 15 o una versión posterior.

  2. Configure uno de los siguientes entornos de prueba:

  3. Inicie su dispositivo de prueba y, a continuación, ejecute el siguiente comando para verificar que está usando un entorno de 16 KB:

    adb shell getconf PAGE_SIZE
    

    El comando debe devolver el valor 16384.

  4. Ejecute el siguiente comando zipalign para verificar que su aplicación está alineada con 16 KB, donde APK_NAME es el nombre de su archivo APK:

    zipalign -c -P 16 -v 4 APK_NAME.apk
    
  5. Pruebe su aplicación a fondo, centrándose en las áreas que puedan verse afectadas por el cambio de instancias de código que hagan referencia a tamaños de página específicos.

Configurar el emulador de Android con una imagen del sistema basada en 16 KB

Para configurar un entorno de 16 KB con el emulador de Android, siga estos pasos:

  1. En Android Studio, haga clic en Herramientas > Gestor de SDK.
  2. En la pestaña Plataformas de SDKs, marque Mostrar detalles del paquete, expanda la sección Android VanillaIceCream o una versión posterior y seleccione una o ambas de las siguientes imágenes del sistema del emulador, en función de los dispositivos virtuales que quiera crear:

    • Imagen del sistema experimental de APIs de Google con tamaño de página de 16 KB para ARM 64 v8a
    • Imagen del sistema experimental de APIs de Google con tamaño de página de 16 KB para Intel x86_64 Atom
    Descargar imágenes del sistema del emulador de 16 kB con el Gestor de SDK de Android Studio
  3. Haga clic en Aplicar > Aceptar para descargar las imágenes del sistema que haya seleccionado.

  4. Siga los pasos para configurar un dispositivo virtual para Android 15 y, cuando se le pida que seleccione una imagen del sistema, seleccione la imagen del sistema de 16 KB que haya descargado. Si no se recomienda automáticamente, puede encontrar la imagen del sistema de 16 KB en la pestaña Otras imágenes.

    Busca la imagen del emulador de 16 KB en la pestaña Otras imágenes.

Iniciar el emulador

Después de configurar el Emulador de Android y los dispositivos virtuales, inicie el emulador desde el menú del dispositivo objetivo o desde la línea de comandos.

Habilita el modo de 16 KB en un dispositivo con las opciones para desarrolladores

Activa la opción para desarrolladores Iniciar con tamaño de página de 16 KB para iniciar un dispositivo en el modo de 16 KB.

En las versiones de QPR de Android 15, puedes usar la opción para desarrolladores disponible en ciertos dispositivos para iniciar el dispositivo en modo de 16 KB y realizar pruebas en el dispositivo. Antes de usar la opción para desarrolladores, ve a Configuración > Sistema > Actualizaciones de software y aplica las actualizaciones disponibles.

Esta opción para desarrolladores está disponible en los siguientes dispositivos:

  • Pixel 8 y 8 Pro (con Android 15 QPR1 o versiones posteriores)

  • Pixel 8a (con Android 15 QPR1 o versiones posteriores)

  • Pixel 9, 9 Pro y 9 Pro XL (con Android 15 QPR2 o versiones posteriores)

  • Pixel 9a (con Android 16 o versiones posteriores)

Modo de compatibilidad con versiones anteriores de 16 KB

Advertencia en el modo de compatibilidad de tamaño de página

Advertencia en el modo de compatibilidad de tamaño de página

La opción de compatibilidad con versiones anteriores de 16 KB está disponible cuando un dispositivo se ejecuta con un kernel de 16 KB. El administrador de paquetes ejecuta una aplicación en el modo de compatibilidad con versiones anteriores de 16 KB cuando se cumplen las siguientes condiciones:

  • Si la aplicación tiene archivos ELF (con la extensión .so) con una alineación de segmento LOAD de 4 KB.
  • Si el APK comprimido tiene archivos ELF sin comprimir que están alineados con ZIP de 4 KB.

Si el administrador de paquetes ha habilitado el modo de compatibilidad con versiones anteriores de 16 KB para una aplicación, la aplicación muestra una advertencia la primera vez que se inicia indicando que se está ejecutando en el modo de compatibilidad con versiones anteriores de 16 KB.

El modo de compatibilidad con versiones anteriores de 16 KB permite que algunas aplicaciones funcionen, pero para obtener la mejor fiabilidad y estabilidad, las aplicaciones deben estar alineadas con 16 KB.

En la página de información de la aplicación, en Avanzado, active o desactive el ajuste Ejecutar aplicación con el modo de compatibilidad de tamaño de página para habilitar o inhabilitar el modo de compatibilidad con versiones anteriores de 16 KB en una aplicación específica. Este ajuste solo se muestra cuando el dispositivo se ejecuta con un tamaño de página de 16 KB.

Ajuste del modo de compatibilidad de tamaño de página

Ajuste del modo de compatibilidad de tamaño de página

Para forzar la activación de la compatibilidad con versiones anteriores de 16 KB en todas las aplicaciones del dispositivo:

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

Para forzar la desactivación de la compatibilidad con versiones anteriores de 16 KB en todas las aplicaciones del dispositivo:

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

En Android 17, también puede forzar la desactivación de la compatibilidad con versiones anteriores de 16 KB en todas las aplicaciones y hacer que cualquier binario incompatible se anule inmediatamente:

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

Defina la propiedad android:pageSizeCompat como habilitada o inhabilitada para activar o desactivar el modo de compatibilidad con versiones anteriores en una aplicación específica en su AndroidManifest.xml. Cuando se define esta propiedad, la aplicación no muestra advertencias del modo de compatibilidad con versiones anteriores al iniciarse.