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

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

Для написания скриптов Gradle предпочтительнее использовать Kotlin, а не Groovy, поскольку 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: в первую очередь относится к плагину Android Gradle Kotlin DSL или, иногда, к базовому 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
            ...
        }
    ...

Ниже представлен тот же код на языке Kotlin. Обратите внимание, что свойства имеют префикс 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 неявно доступны только типы сборки debug и release. Все остальные пользовательские типы сборки необходимо создавать вручную.

В Groovy можно использовать типы сборки «debug», «release» и некоторые другие, не создавая их предварительно. Следующий фрагмент кода демонстрирует конфигурацию с типами сборки 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 выполнять автодополнение кода и предоставлять другие полезные рекомендации.

Найдите идентификаторы плагинов

В то время как блок buildscript {} добавляет плагины в путь к классам сборки, используя координаты плагина Maven , например com.android.tools.build:gradle:7.4.0 , блок plugins {} вместо этого использует идентификаторы плагинов.

Для большинства плагинов идентификатор плагина — это строка, используемая при их применении с помощью apply plugin . Например, следующие идентификаторы плагинов входят в состав Android Gradle Plugin :

• 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 Plugin Portal , в центральном репозитории Maven Central Repository и в репозитории Google Maven . Подробнее о работе идентификаторов плагинов читайте в статье «Разработка пользовательских плагинов Gradle» .

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

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

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

2. Добавьте плагины в блок plugins {} в файле build.gradle верхнего уровня. Здесь необходимо указать идентификатор и версию плагина. Если плагин не нужно применять к корневому проекту, используйте 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.