Перенесите конфигурацию сборки из 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 и 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 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 repository . Прочтите Developing Custom Gradle Plugins , чтобы узнать больше о том, как работают идентификаторы плагинов.

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

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

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.