В плагине Android Gradle 4.0 добавлена поддержка использования Kotlin в конфигурации сборки Gradle в качестве замены Groovy, языка программирования, традиционно используемого в файлах конфигурации Gradle.
Kotlin предпочтительнее Groovy для написания сценариев Gradle, поскольку Kotlin более удобочитаем и предлагает лучшую проверку во время компиляции и поддержку IDE.
Хотя Kotlin в настоящее время предлагает лучшую интеграцию с редактором кода Android Studio по сравнению с Groovy, сборки с использованием Kotlin, как правило, выполняются медленнее, чем сборки с использованием Groovy, поэтому при принятии решения о миграции учитывайте производительность сборки.
На этой странице представлена основная информация о преобразовании файлов сборки Gradle вашего приложения Android из Groovy в Kotlin. Более подробное руководство по миграции можно найти в официальной документации Gradle.
График
Начиная с Android Studio Giraffe, новые проекты по умолчанию используют Kotlin DSL ( build.gradle.kts
) для настройки сборки. Это обеспечивает более удобные возможности редактирования, чем Groovy DSL ( build.gradle
), с подсветкой синтаксиса, завершением кода и переходом к объявлениям. Чтобы узнать больше, см. Gradle Kotlin DSL Primer .
Общие термины
Kotlin DSL: относится в первую очередь к плагину Kotlin DSL для Android Gradle или, иногда, к базовому Gradle Kotlin DSL .
В этом руководстве по миграции «Kotlin» и «Kotlin DSL» используются как взаимозаменяемые. Аналогично, «Groovy» и «Groovy DSL» используются как взаимозаменяемые.
Именование файла сценария
Имена расширений файлов сценариев зависят от языка, на котором написан файл сборки:
- Файлы сборки Gradle, написанные на Groovy, используют расширение имени файла
.gradle
. - Файлы сборки Gradle, написанные на Kotlin, используют расширение имени файла
.gradle.kts
.
Преобразование синтаксиса
Между Groovy и Kotlin существуют некоторые общие различия в синтаксисе, поэтому вам необходимо применять эти изменения во всех сценариях сборки.
Добавляйте круглые скобки к вызовам методов
Groovy позволяет опускать круглые скобки при вызове методов, тогда как Kotlin требует этого. Чтобы перенести конфигурацию, добавьте круглые скобки к такого рода вызовам методов. Этот код показывает, как настроить параметр в Groovy:
compileSdkVersion 30
Это тот же код, написанный на Kotlin:
compileSdkVersion(30)
Добавить =
к вызовам присваивания
Groovy DSL позволяет опускать оператор присваивания =
при назначении свойств, тогда как Kotlin этого требует. Этот код показывает, как назначать свойства в Groovy:
java {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
Этот код показывает, как назначать свойства в Kotlin:
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
Преобразование строк
Вот различия строк между Groovy и Kotlin:
- Двойные кавычки для строк. В то время как Groovy позволяет определять строки с помощью одинарных кавычек, Kotlin требует двойных кавычек.
Строковая интерполяция в выражениях с точками. В Groovy вы можете использовать только префикс
$
для интерполяции строк в выражениях с точками, но Kotlin требует, чтобы вы заключали выражения с точками в фигурные скобки. Например, в Groovy вы можете использовать$project.rootDir
, как показано в следующем фрагменте:myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
Однако в Kotlin предыдущий код вызывает
toString()
дляproject
, а не дляproject.rootDir
. Чтобы получить значение корневого каталога, заключите выражение${project.rootDir}
в фигурные скобки:myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
Дополнительные сведения см. в разделе Шаблоны строк в документации Kotlin.
Переименуйте расширения файлов
Добавляйте .kts
к каждому файлу сборки при переносе его содержимого. Например, выберите файл сборки, например файл settings.gradle
. Переименуйте файл в settings.gradle.kts
и преобразуйте содержимое файла в Kotlin. Убедитесь, что ваш проект по-прежнему компилируется после переноса каждого файла сборки.
Сначала перенесите самые маленькие файлы, наберитесь опыта, а затем двигайтесь дальше. В проекте можно использовать смесь файлов сборки Kotlin и Groovy, поэтому не торопитесь и осторожно делайте этот шаг.
Замените def
на val
или var
Замените def
на val
или var
— именно так вы определяете переменные в Kotlin . Это объявление переменной в Groovy:
def building64Bit = false
Это тот же код, написанный на Kotlin:
val building64Bit = false
Префикс логических свойств с помощью is
Groovy использует логику вывода свойств на основе имен свойств. Для логического свойства foo
его выведенными методами могут быть getFoo
, setFoo
или isFoo
. Таким образом, после преобразования в Kotlin вам необходимо изменить имена свойств на выведенные методы, которые не поддерживаются Kotlin. Например, для логических элементов DSL buildTypes
необходимо иметь префикс is
. Этот код показывает, как установить логические свойства в Groovy:
android {
buildTypes {
release {
minifyEnabled true
shrinkResources true
...
}
debug {
debuggable true
...
}
...
Ниже приведен тот же код в Котлине. Обратите внимание, что свойства имеют префикс is
.
android {
buildTypes {
getByName("release") {
isMinifyEnabled = true
isShrinkResources = true
...
}
getByName("debug") {
isDebuggable = true
...
}
...
Преобразование списков и карт
Списки и карты в Groovy и Kotlin определяются с использованием разного синтаксиса. Groovy использует []
, а Kotlin явно вызывает методы создания коллекции, используя listOf
или mapOf
. При миграции обязательно замените []
на listOf
или mapOf
.
Вот как определить список в Groovy и Kotlin:
jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]
Это тот же код, написанный на Kotlin:
jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")
Вот как определить карту в Groovy и Kotlin:
def myMap = [key1: 'value1', key2: 'value2']
Это тот же код, написанный на Kotlin:
val myMap = mapOf("key1" to "value1", "key2" to "value2")
Настройка типов сборки
В Kotlin DSL неявно доступны только типы сборки отладки и выпуска. Все остальные типы пользовательских сборок необходимо создавать вручную.
В Groovy вы можете использовать отладочные, выпускные и некоторые другие типы сборок, не создавая их предварительно. В следующем фрагменте кода показана конфигурация с типами сборки debug
, release
и benchmark
в Groovy.
buildTypes {
debug {
...
}
release {
...
}
benchmark {
...
}
}
Чтобы создать эквивалентную конфигурацию в Kotlin, вы должны явно создать тип сборки benchmark
.
buildTypes {
debug {
...
}
release {
...
}
register("benchmark") {
...
}
}
Миграция со buildscript на блок плагинов
Если ваша сборка использует блок buildscript {}
для добавления плагинов в проект, вам следует выполнить рефакторинг, чтобы вместо этого использовать блок plugins {}
. Блок plugins {}
упрощает применение плагинов и хорошо работает с каталогами версий .
Кроме того, когда вы используете блок plugins {}
в файлах сборки, Android Studio учитывает контекст, даже если сборка завершается неудачей. Этот контекст помогает вносить исправления в файлы Kotlin DSL, поскольку позволяет Studio IDE выполнять автодополнение кода и предоставлять другие полезные предложения.
Найдите идентификаторы плагинов
Хотя блок buildscript {}
добавляет плагины в путь к классам сборки, используя координаты плагина Maven , например com.android.tools.build:gradle:7.4.0
, блок plugins {}
вместо этого использует идентификаторы плагинов.
Для большинства плагинов идентификатор плагина — это строка, используемая при их применении с помощью apply plugin
. Например, следующие идентификаторы плагинов являются частью плагина Android Gradle :
-
com.android.application
-
com.android.library
-
com.android.lint
-
com.android.test
Полный список плагинов вы можете найти в репозитории Google Maven .
На плагины Kotlin можно ссылаться по нескольким идентификаторам плагинов. Мы рекомендуем использовать идентификатор плагина в пространстве имен и выполнить рефакторинг от сокращенного идентификатора плагина в пространстве имен по следующей таблице:
Сокращенные идентификаторы плагинов | Идентификаторы плагинов в пространстве имен |
---|---|
kotlin | org.jetbrains.kotlin.jvm |
kotlin-android | org.jetbrains.kotlin.android |
kotlin-kapt | org.jetbrains.kotlin.kapt |
kotlin-parcelize | org.jetbrains.kotlin.plugin.parcelize |
Вы также можете искать плагины на портале плагинов Gradle , в центральном репозитории Maven и в репозитории Google Maven . Прочтите статью «Разработка пользовательских плагинов Gradle» , чтобы узнать больше о том, как работают идентификаторы плагинов.
Выполните рефакторинг
Как только вы узнаете идентификаторы используемых вами плагинов, выполните следующие шаги:
Если у вас все еще есть репозитории для плагинов, объявленные в блоке
buildscript {}
, переместите их в файлsettings.gradle
.Добавьте плагины в блок
plugins {}
в файлеbuild.gradle
верхнего уровня. Здесь необходимо указать ID и версию плагина. Если плагин не нужно применять к корневому проекту, используйтеapply false
.Удалите записи
classpath
из файлаbuild.gradle.kts
верхнего уровня.Примените плагины, добавив их в блок
plugins {}
в файлеbuild.gradle
уровня модуля. Здесь вам нужно указать только идентификатор плагина, поскольку версия наследуется от корневого проекта.Удалите вызов
apply plugin
для плагина из файлаbuild.gradle
уровня модуля.
Например, в этой настройке используется блок buildscript {}
:
// Top-level build.gradle file
buildscript {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
dependencies {
classpath("com.android.tools.build:gradle:7.4.0")
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
...
}
}
// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")
Это эквивалентная настройка с использованием блока plugins {}
:
// Top-level build.gradle file
plugins {
id 'com.android.application' version '7.4.0' apply false
id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
...
}
// Module-level build.gradle file
plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
...
}
// settings.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
Преобразование блока плагинов
Применение плагинов из блока plugins {}
в Groovy и Kotlin аналогично. Следующий код показывает, как применять плагины в Groovy при использовании каталогов версий :
// Top-level build.gradle file
plugins {
alias libs.plugins.android.application apply false
...
}
// Module-level build.gradle file
plugins {
alias libs.plugins.android.application
...
}
Следующий код показывает, как сделать то же самое в Kotlin:
// Top-level build.gradle.kts file
plugins {
alias(libs.plugins.android.application) apply false
...
}
// Module-level build.gradle.kts file
plugins {
alias(libs.plugins.android.application)
...
}
Следующий код показывает, как применять плагины в Groovy, когда вы не используете каталоги версий:
// Top-level build.gradle file
plugins {
id 'com.android.application' version '7.3.0' apply false
...
}
// Module-level build.gradle file
plugins {
id 'com.android.application'
...
}
Следующий код показывает, как сделать то же самое в Kotlin:
// Top-level build.gradle.kts file
plugins {
id("com.android.application") version "7.3.0" apply false
...
}
// Module-level build.gradle.kts file
plugins {
id("com.android.application")
...
}
Дополнительные сведения о блоке plugins {}
см. в разделе «Применение плагинов» в документации Gradle.
Разнообразный
Примеры кода Kotlin для других функций см. на следующих страницах документации:
- Если у вас есть конфигурация ProGuard, см. раздел Включение сжатия, обфускации и оптимизации .
- Если у вас есть блок
signingConfig {}
, см. раздел Удаление информации о подписи из файлов сборки . - Если вы используете свойства на уровне проекта, см. раздел Настройка свойств на уровне проекта .
Известные вопросы
В настоящее время известная проблема заключается в том, что скорость сборки в Kotlin может быть медленнее, чем в Groovy.
Как сообщить о проблемах
Инструкции о том, как предоставить информацию, необходимую для рассмотрения вашей проблемы, см. в разделе Подробности об инструментах сборки и ошибках Gradle . Затем сообщите об ошибке, используя общедоступную систему отслеживания ошибок Google.
Больше ресурсов
Рабочий пример файлов сборки Gradle, написанных с помощью Kotlin, см. в примере приложения Now In Android на GitHub.