Перенесите конфигурацию сборки из Groovy в Kotlin.

В плагине Android Gradle 4.0 добавлена ​​поддержка использования Kotlin в конфигурации сборки Gradle в качестве замены Groovy, языка программирования, традиционно используемого в файлах конфигурации Gradle.

Kotlin предпочтительнее Groovy для написания сценариев Gradle, поскольку Kotlin более удобочитаем и предлагает лучшую проверку во время компиляции и поддержку IDE.

Хотя Kotlin в настоящее время предлагает лучшую интеграцию с редактором кода Android Studio по сравнению с Groovy, сборки с использованием Kotlin, как правило, выполняются медленнее, чем сборки с использованием Groovy, поэтому при принятии решения о миграции учитывайте производительность сборки.

На этой странице представлена ​​основная информация о преобразовании файлов сборки Gradle вашего приложения Android из Groovy в Kotlin. Более подробное руководство по миграции можно найти в официальной документации Gradle.

График

Примечание. Kotlin является языком по умолчанию для конфигурации сборки, начиная с Android Studio Giraffe. Если вы используете AGP 8.1 и Kotlin DSL для настройки сборки, для наилучшего результата вам следует использовать Gradle 8.1.

Начиная с 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 позволяет опускать круглые скобки при вызове методов, тогда как Kotlin требует этого. Чтобы перенести конфигурацию, добавьте круглые скобки к такого рода вызовам методов. Этот код показывает, как настроить параметр в Groovy:

compileSdkVersion 30

Это тот же код, написанный на Kotlin:

compileSdkVersion(30)

Добавить = к вызовам присваивания

Совет: Прежде чем менять расширения файлов, добавьте = в код Groovy. Это упрощает переход на Kotlin.

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» , чтобы узнать больше о том, как работают идентификаторы плагинов.

Выполните рефакторинг

Как только вы узнаете идентификаторы используемых вами плагинов, выполните следующие шаги:

1. Если у вас все еще есть репозитории для плагинов, объявленные в блоке buildscript {} , переместите их в файл settings.gradle .

2. Добавьте плагины в блок plugins {} в файле build.gradle верхнего уровня. Здесь необходимо указать ID и версию плагина. Если плагин не нужно применять к корневому проекту, используйте apply false .

3. Удалите записи classpath из файла build.gradle.kts верхнего уровня.

4. Примените плагины, добавив их в блок plugins {} в файле build.gradle уровня модуля. Здесь вам нужно указать только идентификатор плагина, поскольку версия наследуется от корневого проекта.

5. Удалите вызов 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 {} , см. раздел Удаление информации о подписи из файлов сборки .
• Если вы используете свойства на уровне проекта, см. раздел Настройка свойств на уровне проекта .

Внимание: хотя Gradle позволяет определять свойства всего проекта на уровне модуля, избегайте этого, поскольку это приводит к объединению модулей, которые разделяют эти свойства. Соединение модулей затрудняет последующий экспорт модуля как отдельного проекта и не позволяет Gradle использовать параллельное выполнение проекта для ускорения сборки нескольких модулей.

Известные вопросы

В настоящее время известная проблема заключается в том, что скорость сборки в Kotlin может быть медленнее, чем в Groovy.

Как сообщить о проблемах

Инструкции о том, как предоставить информацию, необходимую для рассмотрения вашей проблемы, см. в разделе Подробности об инструментах сборки и ошибках Gradle . Затем сообщите об ошибке, используя общедоступную систему отслеживания ошибок Google.

Больше ресурсов

Рабочий пример файлов сборки Gradle, написанных с помощью Kotlin, см. в примере приложения Now In Android на GitHub.