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

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

Глоссарий

Комплект разработчика Java (JDK)

Комплект разработки Java (JDK) содержит:

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

Среда выполнения JetBrains (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 executable in the PATH environment variable

Как выбрать, какой 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. Повторное использование демона сокращает время запуска новой JVM и инициализации системы сборки.

Если вы запускаете сборки с разными версиями 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.

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

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

Например, для Android Gradle Plugin версии 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 = 33
}

android {
    ...
    compileSdk 33
}

Каждая версия Android поддерживает определённую версию JDK и подмножество доступных API Java. Если вы используете API Java, доступный в compileSdk , но недоступный в указанном minSdk , вы можете использовать его в более ранней версии 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 и jvmTarget определяют версию формата класса Java, используемую при генерации байт-кода для скомпилированного исходного кода Java и Kotlin соответственно.

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

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

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

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget '17'
    }
}

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