Versiones de Java en compilaciones de Android

Ya sea que tu código fuente esté escrito en Java, Kotlin o ambos, hay varios lugares en los que debes elegir una versión de JDK o de lenguaje Java para tu compilación.

Glosario

Kit de desarrollo de Java (JDK)

El Java Development Kit (JDK) contiene lo siguiente:

• Herramientas, como un compilador, un generador de perfiles y un creador de archivos Se usan tras bambalinas durante la compilación para crear tu aplicación.
• Bibliotecas que contienen APIs a las que puedes llamar desde tu código fuente de Kotlin o Java Ten en cuenta que no todas las funciones están disponibles en Android.
• La máquina virtual de Java (JVM), un intérprete que ejecuta aplicaciones de Java La JVM se usa para ejecutar el IDE de Android Studio y la herramienta de compilación de Gradle. La JVM no se usa en dispositivos ni emuladores Android.

Entorno de ejecución de JetBrains (JBR)

JetBrains Runtime (JBR) es un JDK mejorado que se distribuye con Android Studio. Incluye varias optimizaciones para usar en Studio y productos relacionados de JetBrains, pero también se puede usar para ejecutar otras aplicaciones de Java.

¿Cómo elijo un JDK para ejecutar Android Studio?

Te recomendamos que uses JBR para ejecutar Android Studio. Se implementa con Android Studio y se usa para probarlo, y, además, incluye mejoras para un uso óptimo de Android Studio. Para garantizar esto, no configures la variable de entorno STUDIO_JDK.

Las secuencias de comandos de inicio de Android Studio buscan una JVM en el siguiente orden:

1. Con la variable de entorno STUDIO_JDK.
2. Directorio studio.jdk (en la distribución de Android Studio)
3. Directorio jbr (JetBrains Runtime) en la distribución de Android Studio Es la opción recomendada.
4. Con la variable de entorno JDK_HOME.
5. Con la variable de entorno JAVA_HOME.
6. El ejecutable java en la variable de entorno PATH

¿Cómo elijo qué JDK ejecuta mis compilaciones de Gradle?

Si ejecutas Gradle con los botones de Android Studio, se usará el JDK establecido en la configuración de Android Studio para ejecutar Gradle. Si ejecutas Gradle en una terminal, ya sea dentro o fuera de Android Studio, la variable de entorno JAVA_HOME (si está configurada) determina qué JDK ejecuta las secuencias de comandos de Gradle. Si no se establece JAVA_HOME, se usa el comando java en la variable de entorno PATH.

Para obtener los resultados más coherentes, asegúrate de establecer la variable de entorno JAVA_HOME y la configuración del JDK de Gradle en Android Studio en ese mismo JDK.

Cuando ejecutas tu compilación, Gradle crea un proceso llamado daemon para realizar la compilación real. Este proceso se puede reutilizar, siempre y cuando las compilaciones usen la misma versión de JDK y Gradle. Reutilizar un daemon reduce el tiempo para iniciar una JVM nueva y, además, inicializa el sistema de compilación.

Si inicias compilaciones con diferentes JDK o versiones de Gradle, se crean daemons adicionales, lo que consume más CPU y memoria.

Configuración del JDK de Gradle en Android Studio

Para modificar la configuración de JDK de Gradle del proyecto existente, abre la configuración de Gradle desde File (o Android Studio en macOS) > Settings > Build, Execution, Deployment > Build Tools > Gradle. El menú desplegable Gradle JDK contiene las siguientes opciones para seleccionar:

• Macros como JAVA_HOME y GRADLE_LOCAL_JAVA_HOME
• Entradas de la tabla de JDK en formato vendor-version, como jbr-17, que se almacenan en los archivos de configuración de Android
• Cómo descargar un JDK
• Agrega un JDK específico
• JDK detectados de forma local desde el directorio de instalación de JDK predeterminado del sistema operativo

La opción seleccionada se almacena en la opción gradleJvm del archivo .idea/gradle.xml del proyecto, y su resolución de ruta de acceso del JDK se usa para ejecutar Gradle cuando se inicia a través de Android Studio.

Las macros habilitan la selección dinámica de la ruta de acceso del JDK del proyecto:

• JAVA_HOME: Usa la variable de entorno con el mismo nombre.
• GRADLE_LOCAL_JAVA_HOME: Usa la propiedad java.home en el archivo .gradle/config.properties, que se establece de forma predeterminada en el entorno de ejecución de JetBrains.

El JDK seleccionado se usa para ejecutar tu compilación de Gradle y resolver las referencias de la API del JDK cuando editas tus secuencias de comandos de compilación y el código fuente. Ten en cuenta que el compileSdk especificado restringirá aún más los símbolos de Java que estarán disponibles cuando edites y compiles tu código fuente.

Asegúrate de elegir una versión de JDK que sea superior o igual a las versiones de JDK que usan los complementos que utilizas en tu compilación de Gradle. Para determinar la versión mínima requerida del JDK para el complemento de Android para Gradle (AGP), consulta la tabla de compatibilidad en las notas de la versión.

Por ejemplo, la versión 8.x del complemento de Android para Gradle requiere el JDK 17. Si intentas ejecutar una compilación de Gradle que lo use con una versión anterior del JDK, se mostrará un mensaje como el siguiente:

An exception occurred applying plugin request [id: 'com.android.application']
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in /usr/local/buildtools/java/jdk
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

¿Qué APIs de Java puedo usar en mi código fuente de Java o Kotlin?

Una aplicación para Android puede usar algunas de las APIs definidas en un JDK, pero no todas. El SDK de Android define implementaciones de muchas funciones de la biblioteca de Java como parte de sus APIs disponibles. La propiedad compileSdk especifica qué versión del SDK de Android se debe usar cuando se compila el código fuente de Kotlin o Java.

android {
    ...
    compileSdk = 36
}

android {
    ...
    compileSdk 36
}

Cada versión de Android admite una versión específica del JDK y un subconjunto de sus APIs de Java disponibles. Si usas una API de Java que está disponible en un compileSdk que no está disponible en el minSdk especificado, es posible que puedas usar la API en la versión anterior de Android a través de un proceso conocido como desugaring. Consulta las APIs de Java 11 y versiones posteriores disponibles con la expansión de sintaxis para conocer las APIs compatibles.

Usa esta tabla para determinar qué versión de Java es compatible con cada API de Android y dónde encontrar detalles sobre qué APIs de Java están disponibles.

¿Qué JDK compila mi código fuente de Java?

El JDK de la cadena de herramientas de Java contiene el compilador de Java que se usa para compilar cualquier código fuente de Java. Este JDK también ejecuta javadoc y pruebas de unidades durante la compilación.

La cadena de herramientas se establece de forma predeterminada en el JDK que se usa para ejecutar Gradle. Si usas la versión predeterminada y ejecutas una compilación en diferentes máquinas (por ejemplo, tu máquina local y un servidor de integración continua independiente), los resultados de la compilación pueden variar si se usan diferentes versiones del JDK.

Para crear una compilación más coherente, puedes especificar de forma explícita una versión de la cadena de herramientas de Java. Si especificas esto, ocurrirá lo siguiente:

• Ubica un JDK compatible en el sistema que ejecuta la compilación.
  • Si no existe un JDK compatible (y se define un agente de resolución de cadenas de herramientas), descarga uno.
• Expone las APIs de Java de la cadena de herramientas para las llamadas desde el código fuente.
• Compila el código fuente de Java con su versión del lenguaje Java.
• Proporciona valores predeterminados para sourceCompatibility y targetCompatibility.

Te recomendamos que siempre especifiques la cadena de herramientas de Java y que te asegures de que el JDK especificado esté instalado o que agregues un solucionador de cadenas de herramientas a tu compilación.

Puedes especificar la cadena de herramientas, ya sea que tu código fuente esté escrito en Java, Kotlin o ambos. Especifica la cadena de herramientas en el nivel superior del archivo build.gradle(.kts) de tu módulo.

Especifica la versión de la cadena de herramientas de Java de la siguiente manera:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Esto funciona si tu fuente es Kotlin, Java o una combinación de ambos.

La versión del JDK de la cadena de herramientas puede ser la misma que la del JDK que se usa para ejecutar Gradle, pero ten en cuenta que tienen diferentes propósitos.

¿Qué funciones de origen del lenguaje Java puedo usar en mi código fuente de Java?

La propiedad sourceCompatibility determina qué funciones del lenguaje Java están disponibles durante la compilación de la fuente de Java. No afecta la fuente de Kotlin.

Especifica sourceCompatibility en el archivo build.gradle(.kts) de tu módulo de la siguiente manera:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

Si no se especifica, esta propiedad se establece de forma predeterminada en la versión de la cadena de herramientas de Java. Si no usas una cadena de herramientas de Java, se establece de forma predeterminada en una versión elegida por el complemento de Android para Gradle (por ejemplo, Java 8 o una versión posterior).

¿Qué funciones binarias de Java se pueden usar cuando compilo mi código fuente de Kotlin o Java?

La propiedad targetCompatibility determina la versión del formato de clase de Java que se usa cuando se genera el código de bytes para el código fuente compilado de Java y Kotlin, respectivamente.

Algunas funciones de Kotlin existían antes de que se agregaran las funciones equivalentes de Java. Los primeros compiladores de Kotlin tuvieron que crear su propia forma de representar esas funciones de Kotlin. Algunas de estas funciones se agregaron más tarde a Java. Con niveles de targetCompatibility posteriores, el compilador de Kotlin puede usar directamente la función de Java, lo que podría mejorar el rendimiento.

Las diferentes versiones de Android admiten diferentes versiones de Java. Puedes aprovechar las funciones adicionales de Java aumentando targetCompatibility, pero esto podría obligarte a aumentar también la versión mínima del SDK de Android para garantizar que la función esté disponible.

Ten en cuenta que targetCompatibility debe ser mayor o igual que sourceCompatibility. En la práctica, sourceCompatibility y targetCompatibility deberían usar, por lo general, el mismo valor. Puedes configurarlos de la siguiente manera:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

Si usas una versión de Kotlin anterior a la 2.2, también debes configurar kotlinOptions:

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

Si no se especifican, estas propiedades se establecen de forma predeterminada en la versión de la cadena de herramientas de Java. Si no usas una cadena de herramientas de Java, los valores predeterminados pueden variar y causar problemas de compilación. Por lo tanto, te recomendamos que siempre especifiques estos valores de forma explícita o que uses una cadena de herramientas de Java.