Gradle Convention Plugins: как облегчить себе жизнь и уменьшить boilerplate в gradle-файлах

Привет, Хабр! Я Дима Котиков, ведущий android-разработчик в Т-Банке. Работаю в команде приложения Долями. Разработкой под Android начал увлекаться в 2020 году, а потом хобби переросло в работу. Люблю разбираться в технологиях, разрабатывать под Android и KMP и латте на фундучном молоке 🙂

Я расскажу о том, как облегчить работу с Gradle с использованием Gradle Convention Plugins. Всю информацию я разбил на серию статей для удобства. Они будут полезны всем, кто пользуется Gradle в качестве сборщика проектов. В первой части поговорим о проблеме с build.gradle-файлами и сделаем начальную настройку для написания Gradle Convention Plugins.

build.gradle.kts — монстр

Каждый android-разработчик так или иначе сталкивается со сборщиком проектов Gradle и видит в своих модулях файлы build.gradle или build.gradle.kts. Дальше примеры будут на базе build.gradle.kts-файлов для kotlin-multiplatform-проекта, но в целом информация применима и к build.gradle.

import org.jetbrains.compose.ExperimentalComposeLibrary import org.jetbrains.compose.desktop.application.dsl.TargetFormat import com.android.build.api.dsl.ManagedVirtualDevice import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi import org.jetbrains.kotlin.gradle.dsl.JvmTarget import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSetTree    plugins {     alias(libs.plugins.multiplatform)     alias(libs.plugins.compose.compiler)     alias(libs.plugins.compose)     alias(libs.plugins.android.application)     alias(libs.plugins.kotlinx.serialization) } kotlin {     androidTarget {         compilations.all {             compileTaskProvider {                 compilerOptions {                     jvmTarget.set(JvmTarget.JVM_1_8)                     freeCompilerArgs.add("-Xjdk-release=${JavaVersion.VERSION_1_8}")                 }             }         }         //https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-test.html         @OptIn(ExperimentalKotlinGradlePluginApi::class)         instrumentedTestVariant {             sourceSetTree.set(KotlinSourceSetTree.test)             dependencies {                 debugImplementation(libs.androidx.testManifest)                 implementation(libs.androidx.junit4)             }         }     }     jvm()        listOf(         iosX64(),         iosArm64(),         iosSimulatorArm64()     ).forEach {         it.binaries.framework {             baseName = "ComposeApp"             isStatic = true         }     }     sourceSets {         commonMain.dependencies {             implementation(project(":shared-uikit"))                implementation(compose.runtime)             implementation(compose.foundation)             implementation(compose.material3)             implementation(compose.components.resources)             implementation(compose.components.uiToolingPreview)             implementation(libs.coil)             implementation(libs.coil.network.ktor)             implementation(libs.kotlinx.coroutines.core)             implementation(libs.ktor.core)             implementation(libs.kotlinx.serialization.json)             implementation(libs.kotlinx.datetime)         }         commonTest.dependencies {             implementation(kotlin("test"))             @OptIn(ExperimentalComposeLibrary::class)             implementation(compose.uiTest)             implementation(libs.kotlinx.coroutines.test)         }         androidMain.dependencies {             implementation(compose.uiTooling)             implementation(libs.androidx.activityCompose)             implementation(libs.kotlinx.coroutines.android)             implementation(libs.ktor.client.okhttp)         }         jvmMain.dependencies {             implementation(compose.desktop.currentOs)             implementation(libs.kotlinx.coroutines.swing)            implementation(libs.ktor.client.okhttp)         }         iosMain.dependencies {             implementation(libs.ktor.client.darwin)         }     } }   android {     namespace = "io.github.dmitriy1892.gradleconventionpuginssample"     compileSdk = 34     defaultConfig {         minSdk = 24         targetSdk = 34         applicationId = "io.github.dmitriy1892.gradleconventionpuginssample.androidApp"         versionCode = 1         versionName = "1.0.0"         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"     }     sourceSets["main"].apply {         manifest.srcFile("src/androidMain/AndroidManifest.xml")         res.srcDirs("src/androidMain/res")     }     //https://developer.android.com/studio/test/gradle-managed-devices     @Suppress("UnstableApiUsage")     testOptions {         managedDevices.devices {             maybeCreate<ManagedVirtualDevice>("pixel5").apply {                 device = "Pixel 5"                 apiLevel = 34                 systemImageSource = "aosp"             }         }     }     compileOptions {         sourceCompatibility = JavaVersion.VERSION_1_8         targetCompatibility = JavaVersion.VERSION_1_8     }     buildFeatures {         //enables a Compose tooling support in the AndroidStudio         compose = true     } }   compose.desktop {     application {         mainClass = "MainKt"         nativeDistributions {             targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)             packageName = "io.github.dmitriy1892.gradleconventionpuginssample.desktopApp"             packageVersion = "1.0.0"         }     } }

Код выглядит монструозно. Если проект многомодульный, в каждом модуле содержится build.gradle.kts-файл примерно с таким же наполнением.

Все бы ничего, но есть моменты, которые могут доставить проблем и заставить вручную пройти по всем модулям, если держать конфигурации модулей как в примере. Так может случиться, когда нужно:

1. Поднять версии библиотек, minSdk/targetSdk/compileSdk или Java;

2. Поднять версию Gradle-wrapper или Android Gradle Plugin, что в случае изменения API классов или функций gradle-конфигураций может повлечь необходимость изменений в файлах build.gradle.kts каждого модуля;

3. Обработать deprecation-ы разного рода конфигураций в новых версиях Gradle Plugin, AGP, KMP и тому подобное:

4. Копипастить все из build.gradle.kts при необходимости создать модуль вручную и нудно настраивать под конкретный модуль.

Хочется избавиться от этого списка проблем, повторяющихся частей, соблюсти DRY. На помощь может прийти Gradle Convention Plugins.

Gradle Convention Plugins

Gradle Convention Plugins — это инструмент, позволяющий переиспользовать конфигурации сборки, уменьшить Boilerplate в build.gradle.kts-файлах и проще управлять изменениями при смене версий библиотек, плагинов и тому подобного. А еще он упрощает поддержку конфигураций сборки.

Для использования механизма нужно создать модуль для Convention Plugins, выделить базовые конфигурации, применить их при написании Convention Plugins, зарегистрировать плагины в build.gradle.kts нашего модуля с плагинами и использовать в проекте. 

На каждом моменте остановимся подробнее. Используем подход с построением Composite Builds — это подход, в котором наши плагины и конфигурации сборки лежат в отдельных независимых модулях и подключаются к процессу сборки основного проекта. При этом модули с плагинами собираются раньше, чтобы предоставить плагины для сборки нашего проекта.

Пример того, как можно писать Convention Plugins, есть в моем проекте на GitHub, начальный код в ветке initial.

Нам нужно подготовиться, чтобы написать Convention Plugins:

1. Создать gradle-модуль, не зависящий от каких-либо других в проекте, — в нем мы будем размещать наши будущие Convention Plugins.

2. Подключить модуль с плагинами в корневой проект так, чтобы он собирался до сборки остальных модулей проекта. Результат сборки — скомпилированные Convention Plugins, будем использовать в модулях основного проекта.

3. Сконфигурировать build.gradle.kts и settings.gradle.kts этого модуля правильным образом, чтобы Gradle понимал, что это модуль с плагинами.

По сути, мы будем использовать механизм композитной сборки Gradle — у нас будет независимый модуль, который по системе понятий Gradle будет независимым проектом. После сборки такого проекта его скомпилированные артефакты могут быть использованы другим gradle-проектом, его подмодулями и подпроектами, который подключил наш независимый проект как композит. 

Начинаем настройку для написания Gradle Convention Plugins:

1. Создадим папку convention-plugins в проекте, в ней создадим папку base, в которой будут содержаться базовые конфигурации и extension-функции для наших плагинов. Добавим пустые gradle-файлы base-модуля.

2. Зайдем в settings.gradle.kts и пропишем наш модуль как includeBuild:

Подключение модуля Convention Plugin отличается от подключения обычного модуля функцией includeBuild, а путь прописывается не через двоеточия, а через slash (`/`).
Вот тут как раз и будет работать механизм композитной сборки: сначала соберется модуль или проект, указанный в includeBuild, а потом — основной проект.

3. Конфигурируем build.gradle.kts и settings.gradle.kts для нашего модуля с плагинами.

Конфигурируем settings.gradle.kts — пропишем необходимые репозитории с плагинами и зависимостями, из которых будем запрашивать нужные нам зависимости для использования в наших будущих Convention Plugin-ах:

 import java.net.URI     pluginManagement {      repositories {          google()          gradlePluginPortal()          mavenCentral()          maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")      }  }    dependencyResolutionManagement {      repositories {          google()          mavenCentral()          maven {              url = URI("https://androidx.dev/storage/compose-compiler/repository/")          }      }      versionCatalogs {          create("libs") {              from(files("../../gradle/libs.versions.toml"))          }      }  }  rootProject.name = "base"

Мы указали репозитории для плагинов и зависимостей, прописали создание Version Catalog и указали путь до libs.versions.toml-файла.

Добавляем в libs.versions.toml-файл переменную с версией Java и зависимости нужных нам плагинов и конфигурируем build.gradle.kts модуля convention-plugins/base:

Дублирую зависимости для тех, кто идет по шагам при чтении статьи:

# Plugins for composite build  gradleplugin-android = { module = "com.android.tools.build:gradle", version.ref = "agp" }  gradleplugin-compose = { module = "org.jetbrains.compose:compose-gradle-plugin", version.ref = "compose" }  gradleplugin-composeCompiler = { module = "org.jetbrains.kotlin:compose-compiler-gradle-plugin", version.ref = "compose" }  gradleplugin-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }

Конфигурируем build.gradle.kts модуля convention-plugins/base:

 import org.jetbrains.kotlin.gradle.dsl.JvmTarget  import org.jetbrains.kotlin.gradle.tasks.KotlinCompile     plugins {      `kotlin-dsl`  }      group = "io.github.dmitriy1892.conventionplugins.base"      dependencies {      implementation(libs.gradleplugin.android)      implementation(libs.gradleplugin.compose)      implementation(libs.gradleplugin.composeCompiler)      implementation(libs.gradleplugin.kotlin)      // Workaround for version catalog working inside precompiled scripts      // Issue - https://github.com/gradle/gradle/issues/15383      implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))  }      private val projectJavaVersion: JavaVersion = JavaVersion.toVersion(libs.versions.java.get())     java {      sourceCompatibility = projectJavaVersion      targetCompatibility = projectJavaVersion  }  tasks.withType<KotlinCompile>().configureEach {      compilerOptions.jvmTarget.set(JvmTarget.fromTarget(projectJavaVersion.toString()))  } 

В коде мы сделали следующее:

• В блоке plugins подключили плагин kotlin-dsl, чтобы использовать Gradle Kotlin Dsl для написания наших Convention Plugins;

• В блоке dependencies добавили плагины, которые будем использовать в наших будущих Convention Plugins. Сразу отмечу, что добавлять плагины через блок plugins не получится: такова специфика модуля с Convention Plugin;

• В блоке dependencies добавили Workaround, чтобы в наших плагинах были доступны Version Catalogs. Пока нет возможности по-другому использовать Version Catalogs, есть issue.

• Задали версию Java и kotlin-компилятора.

Создаем первый пустой Convention Plugin и подключаем его к корневому build.gradle.kts нашего проекта. Это нужно для того, чтобы работали extension-функции в build.gradle.kts-файлах модулей корневого проекта, в который мы подключили наш модуль с Convention Plugins.

Предварительную настройку закончили — переходим к созданию базовых Сonvention pugins в .gradle.kts-файлах.

О том, как создавать плагины и переиспользуемые части в .gradle.kts-файлах и Kotlin extension-функций для упрощения написания плагинов — в следующей статье. Не переключайтесь!