Версии Java в сборках Android

Независимо от того, на каком языке написан ваш исходный код (Java, Kotlin или оба), вам нужно выбрать JDK или версию языка Java для сборки в нескольких местах.

Глоссарий

Java Development Kit (JDK)

Java Development Kit (JDK) содержит:

• Инструменты, например компилятор, профилировщик и архиватор. Они используются в фоновом режиме во время сборки для создания приложения.
• Библиотеки, содержащие API, которые можно вызывать из исходного кода на Kotlin или Java. Обратите внимание, что некоторые функции недоступны на устройствах Android.
• Виртуальная машина Java (JVM) – интерпретатор, который выполняет приложения Java. JVM используется для запуска IDE Android Studio и инструмента сборки Gradle. JVM не используется на устройствах Android и эмуляторах.

JetBrains Runtime (JBR)

JetBrains Runtime (JBR)  – это улучшенная версия JDK, которая распространяется вместе с Android Studio. Он включает несколько оптимизаций для использования в Studio и связанных продуктах JetBrains, но также может использоваться для запуска других приложений Java.

Как выбрать JDK для запуска Android Studio?

Мы рекомендуем использовать JBR для запуска Android Studio. Он развертывается вместе с Android Studio и используется для ее тестирования. В него также входят улучшения, которые позволяют оптимально использовать Android Studio. Чтобы этого не произошло, не задавайте переменную среды STUDIO_JDK.

Сценарии запуска Android Studio ищут JVM в следующем порядке:

1. Переменная среды STUDIO_JDK
2. каталог studio.jdk (в дистрибутиве Android Studio);
3. каталог jbr (JetBrains Runtime) в дистрибутиве Android Studio. Рекомендовано.
4. Переменная среды JDK_HOME
5. Переменная среды JAVA_HOME
6. исполняемый файл java в переменной среды PATH.

Как выбрать JDK для сборки Gradle?

Если вы запускаете Gradle с помощью кнопок в Android Studio, для этого используется JDK, заданная в настройках Android Studio. Если вы запускаете Gradle в терминале (в Android Studio или за ее пределами), переменная среды JAVA_HOME (если она задана) определяет, какая версия JDK будет использоваться для выполнения скриптов Gradle. Если параметр JAVA_HOME не задан, используется команда java из переменной среды PATH.

Чтобы результаты были наиболее стабильными, убедитесь, что вы задали переменную среды JAVA_HOME и настроили Gradle JDK в Android Studio на ту же версию JDK.

При выполнении сборки Gradle создает процесс, называемый демоном, который выполняет фактическую сборку. Этот процесс можно использовать повторно, если в сборках используются одинаковые версии JDK и Gradle. Повторное использование демона позволяет сократить время запуска новой виртуальной машины Java и инициализации системы сборки.

Если вы запускаете сборки с разными версиями JDK или Gradle, создаются дополнительные демоны, которые потребляют больше ресурсов ЦП и памяти.

Настройка Gradle JDK в Android Studio

Чтобы изменить конфигурацию Gradle JDK существующего проекта, откройте настройки Gradle, выбрав Файл (или Android Studio на macOS) > Настройки > Сборка, выполнение, развертывание > Инструменты сборки > Gradle. В раскрывающемся списке Gradle JDK можно выбрать следующие варианты:

• Макросы, например JAVA_HOME и GRADLE_LOCAL_JAVA_HOME.
• Записи таблицы JDK в формате vendor-version, например jbr-17, которые хранятся в файлах конфигурации Android.
• Как скачать JDK
• Как добавить определенный JDK
• JDK, обнаруженные локально в каталоге установки JDK по умолчанию в операционной системе.

Выбранный вариант хранится в параметре gradleJvm в файле .idea/gradle.xml проекта, а путь к JDK, определенный этим вариантом, используется для запуска Gradle при запуске через Android Studio.

Макросы позволяют динамически выбирать путь к JDK проекта:

• JAVA_HOME: использует переменную среды с тем же названием.
• GRADLE_LOCAL_JAVA_HOME использует свойство java.home в файле .gradle/config.properties, по умолчанию заданное как JetBrains Runtime.

Выбранный JDK используется для запуска сборки Gradle и разрешения ссылок на API JDK при редактировании скриптов сборки и исходного кода. Обратите внимание, что указанный параметр compileSdk будет ограничивать доступные символы Java при редактировании и сборке исходного кода.

Убедитесь, что версия JDK выше или равна версиям JDK, используемым плагинами, которые вы используете в сборке Gradle. Чтобы узнать минимальную версию JDK, необходимую для плагина Android Gradle (AGP), ознакомьтесь с таблицей совместимости в примечаниях к выпуску.

Например, для плагина Android Gradle версии 8.x требуется JDK 17. Если вы попытаетесь запустить сборку Gradle, в которой используется более ранняя версия JDK, появится сообщение, например:

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`.

Какие API Java можно использовать в исходном коде на Java или Kotlin?

Приложение для Android может использовать некоторые API, определенные в JDK, но не все. Android SDK определяет реализации многих функций библиотеки Java как часть доступных API. Свойство compileSdk указывает, какую версию Android SDK следует использовать при компиляции исходного кода на Kotlin или Java.

android {
    ...
    compileSdk = 36
}

android {
    ...
    compileSdk 36
}

Каждая версия Android поддерживает определенную версию JDK и подмножество доступных Java API. Если вы используете Java API, доступный в compileSdk, которого нет в указанном minSdk, вы можете использовать API в более ранней версии Android с помощью десахаризации. Список поддерживаемых API можно найти в разделе API Java 11 и более поздних версий, доступные через десахаризацию.

В таблице ниже указано, какая версия Java поддерживается каждым API Android и где можно найти информацию о доступных API Java.

Какая версия JDK используется для компиляции исходного кода Java?

Набор инструментов Java JDK содержит компилятор Java, который используется для компиляции любого исходного кода Java. Кроме того, эта версия JDK запускает javadoc и модульное тестирование во время сборки.

По умолчанию в цепочке инструментов используется JDK, которая использовалась для запуска Gradle. Если вы используете настройки по умолчанию и выполняете сборку на разных компьютерах (например, на локальном компьютере и отдельном сервере непрерывной интеграции), результаты сборки могут отличаться, если используются разные версии JDK.

Чтобы сборка была более стабильной, можно явно указать версию цепочки инструментов Java. Указав это:

• Находит совместимый JDK в системе, в которой выполняется сборка.
  • Если совместимый JDK не найден (и определен инструмент разрешения цепочки инструментов), скачивает его.
• Предоставляет доступ к API Java тулчейна для вызовов из исходного кода.
• Компилирует исходный код Java, используя версию языка Java.
• Задает значения по умолчанию для sourceCompatibility и targetCompatibility.

Мы рекомендуем всегда указывать цепочку инструментов Java и либо убедиться, что указанный JDK установлен, либо добавить в сборку разрешитель цепочки инструментов.

Вы можете указать цепочку инструментов, независимо от того, на каком языке написан исходный код: Java, Kotlin или на обоих. Укажите цепочку инструментов на верхнем уровне файла build.gradle(.kts) модуля.

Укажите версию цепочки инструментов Java следующим образом:

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

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

Это работает, если исходный код написан на Kotlin, Java или на обоих языках.

Версия JDK в цепочке инструментов может совпадать с версией JDK, используемой для запуска Gradle, но помните, что они выполняют разные задачи.

Какие функции исходного кода Java можно использовать в исходном коде Java?

Свойство sourceCompatibility определяет, какие функции языка Java доступны при компиляции исходного кода Java. Это не влияет на исходный код Kotlin.

Укажите sourceCompatibility в файле build.gradle(.kts) модуля следующим образом:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

Если значение не указано, по умолчанию используется версия цепочки инструментов Java. Если вы не используете цепочку инструментов Java, по умолчанию будет выбрана версия, которую определяет плагин Android Gradle (например, Java 8 или более поздняя).

Какие функции Java можно использовать при компиляции исходного кода Kotlin или Java?

Свойство targetCompatibility определяет версию формата класса Java, используемую при создании байт-кода для скомпилированного исходного кода Java и Kotlin соответственно.

Некоторые функции Kotlin появились раньше, чем их аналоги в Java. Ранние компиляторы Kotlin должны были создавать собственные способы представления этих функций. Некоторые из этих функций позже были добавлены в Java. На более поздних уровнях targetCompatibility компилятор Kotlin может напрямую использовать функцию Java, что может привести к повышению производительности.

В разных версиях Android поддерживаются разные версии Java. Вы можете использовать дополнительные функции Java, увеличив значение targetCompatibility, но при этом вам, возможно, придется также увеличить минимальную версию Android SDK, чтобы обеспечить доступность функции.

Обратите внимание, что значение targetCompatibility должно быть больше или равно sourceCompatibility. На практике в полях sourceCompatibility и targetCompatibility обычно указывается одно и то же значение. Вы можете задать их следующим образом:

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

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

Если вы используете версию Kotlin ниже 2.2, вам также нужно задать kotlinOptions:

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

Если не указать эти свойства, по умолчанию будет использоваться цепочка инструментов Java. Если вы не используете цепочку инструментов Java, значения по умолчанию могут отличаться и вызывать проблемы при сборке. Поэтому мы рекомендуем всегда явно указывать эти значения или использовать цепочку инструментов Java.