Всем привет! Я пишу приложения под Android, в мире которого система сборки Gradle является стандартом де-факто. Я решил поделиться некоторыми советами по работе с Gradle с теми, у кого нет чёткого понимания, как правильно структурировать свои проекты и писать build-скрипты.

Часто разработчики используют Gradle по наитию и не изучают целенаправленно, потому что не всегда хватает ресурсов на инфраструктурные задачи. А если возникают какие-либо проблемы, то просто копируют готовые куски build-скриптов из ответов на Stack Overflow. Во многом проблема кроется в сложности и чрезмерной гибкости Gradle, а также в отсутствии описания лучших практик в официальной документации.

Поработав больше пяти лет на аутсорсе, я видел много проектов разной сложности. И на всех этих проектах build-скрипты писались по-разному, где-то встречались не очень удачные решения. Я провел небольшую ретроспективу и резюмировал свой опыт в виде разных советов по использованию Gradle и рассказал их на одном из наших внутренних митапов. В статье я перевел эти советы в текст.

Небольшой оффтоп для тех, кому совсем ничего не понятно в Gradle-скриптах

Я заметил, что в Android-сообществе встречаются люди, которые могут годами разрабатывать приложения, но при этом не понимать, как работает Gradle. И достаточно продолжительное время и я был одним из них. Но однажды всё же решил, что гораздо проще потратить время на системное изучение Gradle, чем постоянно натыкаться на непонятные проблемы.

А так как лучший способ изучить что-то — это попытаться рассказать об этом другим людям, то я подготовил рассказ об основах использования Gradle в контексте Android-разработки специально для тех, кто совсем не разбирается в теме. Так что, возможно, этот митап вам поможет.

Теперь к советам.

#1 Не редактируйте Gradle-скрипты через IDE

Android studio умеет генерировать стартовый проект с базовой структурой и готовыми build-скриптами, а также удалять и добавлять модули в существующем проекте. А при редактировании Gradle-скриптов IDE нам заботливо подсказывает, что можно вносить изменения в скрипты через графический интерфейс в меню "File -> Project structure...". И в начале своей карьеры я вполне успешно пользовался этим инструментом. Но у него есть существенный недостаток: IDE не запускает честную фазу конфигурации Gradle и не смотрит на то, что формируется в памяти при сборке, а всего лишь пытается как-то парсить build-скрипты. Зачастую этот инструмент не распознает то, что было написано вручную, что, на мой взгляд, перечеркивает его пользу.

Мой совет: лучше не редактировать скрипты через IDE, а использовать редактор кода.

#2 Обращайте внимание на соглашение по именованию модулей

В Gradle имя проекта (модуля) берется из соответствующего поля name в объекте Project или названия директории, в которой он лежит. В своей практике я видел разные стили именования модулей, например, в camel- или snake- кейсе: MyAwesomeModule, my_awesome_module. Но есть ли какие-то устоявшиеся соглашения об именах модулей? Кажется, официальная документация Gradle ничего нам об этом не говорит. Но нужно принять во внимание тот факт, что проекты Gradle при публикации в Maven будут соответствовать один к одному модулям Maven. И у Maven есть соглашение, что слова в названиях модулей должны разделяться через символ -. То есть правильнее будет такое название модуля: my-awesome-module.

#3 Что выбрать: Kotlin vs Groovy

Изначально в Gradle для DSL использовался язык Groovy, но впоследствии была добавлена возможность писать build-скрипты на Kotlin. Возникает вопрос: что же сейчас использовать? И однозначного ответа на него пока что нет.

Лично я за использование Kotlin, так как не очень хочу только лишь ради build-системы изучать ещё один язык — Groovy. Наверно, для всего Android сообщества DSL на Kotlin существенно понижает порог вхождения в Gradle. Кроме того, у build-скриптов на Kotlin лучше поддержка в IDE с автокомплитом, но, тем не менее, она все еще далека от идеала.

В качестве минуса Kotlin я бы выделил то, что могут встретиться какие-то старые плагины, которые изначально были заточены только под Groovy, и для их подключения придется потратить больше времени.

Если у вас старый большой проект с build-скриптами на Groovy, то могу посоветовать частично попробовать какие-то скрипты перевести на Kotlin, если вам понравится, то можно будет постепенно делать рефакторинг и переписывать все скрипты на Kotlin, не обязательно делать это единовременно.

#4 Как прописывать зависимости в многомодульных проектах

Возьмем небольшой пример проекта со следующей структурой:

Основной модуль, из которого собирается apk, зависит от feature-модулей, а также в нём прописаны какие-то внешние зависимости. feature-модули, в свою очередь, содержат транзитивные зависимости, которые могут пересекаться с зависимостями в других модулях.

В чем проблема такого проекта? Здесь будет тяжело глобально обновлять зависимости в каждом из файлов. Очень легко забыть поднять версию в одном из скриптов, и тогда возникнут конфликты. По умолчанию Gradle умеет разрешать такие конфликты, выбирая максимальную версию, так что, скорее всего, сборка будет успешной (поведение можно менять через resolution strategy).

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

Java platform plugin

Разработчики Gradle предлагают для описания зависимостей создать отдельный специальный модуль, где будут описаны только зависимости с конкретными версиями. К этому модулю надо применить java platform plugin. Далее подключаем этот модуль в остальные модули и при указании каких-то внешних зависимостей не пишем конкретную версию:

Такие platform-проекты можно даже публиковать на внешние maven репозитории и переиспользовать. В качестве минуса подхода можно назвать то, что при мажорных обновлениях библиотек часто меняются не только версии, но и названия модулей, и тогда все равно придется вносить изменения сразу в нескольких скриптах.

Перейду к общепринятым в сообществе способам описания зависимостей.

Описание зависимостей в extra properties

Достаточно часто можно увидеть практику, когда строки с зависимостями хранят в extra properties корневого проекта, по сути это словарь, доступный всем дочерним модулям. Пример использования можно встретить в некоторых библиотеках от Google.

В корневом проекте описываем зависимости. Вот кусок build-скрипта из библиотеки Google, где зависимость возвращается функцией compatibility:

ext {
    compileSdkVersion = 29
    minSdkVersion = 14
    targetSdkVersion = 29

    androidXVersions = [
            annotation: '1.0.1',
            appCompat: '1.1.0'
      // ...
    ]
}
/**
 * Return the module dependency for the given compatibility library name.
 */
def compatibility(name) {
  switch (name) {
    case "annotation":
      return "androidx.annotation:annotation:${androidXVersions.annotation}"
    case "appcompat":
      return "androidx.appcompat:appcompat:${androidXVersions.appCompat}"

И обращаемся к ним из дочерних модулей:

dependencies {
    api compatibility("annotation")
    api compatibility("appcompat")
    api compatibility("cardview")
    api compatibility("coordinatorlayout")
    api compatibility("constraintlayout")
    api compatibility("core")
    api compatibility("dynamicanimation")
    // ...
}

Описание зависимостей в скриптовом плагине

Описанный способ с extra properties можно немного модифицировать и вынести описание зависимостей в скриптовый плагин, чтобы не засорять корневой проект. А уже скриптовый плагин можно применить или к корневому, или ко всем дочерним проектам сразу (через allprojects {}), или к отдельным. Такой способ я тоже встречал.

Описание зависимостей в buildSrc

В buildSrc можно писать любой код, который будет компилироваться и добавляться в classpath build-скриптов. В последнее время стало популярно использовать buildSrc для описания там зависимостей. Например, в библиотеке Insetter Chris Banes так и делает.

Все, что нужно, — это добавить синглтон со строками в buildSrc, и он станет виден всем модулям в проекте:

object Versions {
    const val minSdk = 23
    const val compileSdk = 29
    const val kotlin = "1.4.20"
    const val kotlinCoroutines = "1.4.0"
    const val okHttp = "4.9.0"
    const val retrofit = "2.9.0"
    const val moshi = "1.11.0"
}
object Dependencies {
    object Kotlin {
        const val stdlib = "org.jetbrains.kotlin:kotlin-stdlib:${Versions.kotlin}"
        const val reflect = “org.jetbrains.kotlin:kotlin-reflect:${Versions.kotlin}"
    }
    object Google {
        const val materialComponents = "com.google.android.material:material:1.2.1"
        const val googleAuth = "com.google.android.gms:play-services-auth:18.1.0"
        const val location = "com.google.android.gms:play-services-location:17.1.0"
        const val tasks = "com.google.android.gms:play-services-tasks:17.2.0"
    }
}

Использовать buildSrc для зависимостей очень удобно, так как будут статические проверки и автокомплит в IDE:

Но у этого решения есть один недостаток: любое изменение в buildSrc будет инвалидировать весь кэш сборки, что может быть несущественно для средних и маленьких проектов, но выливаться в серьезные проблемы для больших команд.

Композитные сборки

Можно достичь похожего результата со статическими проверками и автокомплитом, используя композитные сборки, при этом избавившись от проблемы инвалидации всего кэша. Я расскажу про него лишь кратко, а подробный гайд по миграции с buildSrc можно прочитать в статье из блога Badoo или статье от Josef Raska.

В композитных сборках мы создаем так называемые «включенные сборки» (included build), в которых можно писать плагины и подключать их в своих модулях. Включенные сборки описываются в файле settings.gradle.

Если мы хотим всего лишь подсунуть в classpath build-скриптов строки с зависимостями, то достаточно создать пустой плагин, а рядом с ним положить тот же файл с зависимостями, который мы использовали раньше в buildSrc:

// Build скрипт включенной сборки
// ./dependencies/build.gradle.kts

plugins {
    `kotlin-dsl`
}

repositories {
    jcenter()
    google()
}

gradlePlugin {
    plugins {
        register("dependencies") {
            id = "dependencies"
            implementationClass = “com.rmr.dependencies.DependenciesPlugin”
        }
    }
}

// Плагин из включенной сборки
// ./dependencies/src/main/kotlin/com/rmr/depenendencies/DependenciesPlugin.kt
package com.rmr.dependencies

import org.gradle.api.Plugin
import org.gradle.api.Project

class DependenciesPlugin : Plugin<Project> {

    override fun apply(target: Project) {
        // Do nothing, just load dependencies to classpath
    }
}

Все, что осталось сделать, — применить плагин к корневому проекту:

plugins { id("dependencies") }

И мы получим практически тот же результат, как и с использованием buildSrc.

Выглядит так, что способ с композитными сборками самый подходящий и его можно сразу начинать использовать со старта проекта.

#5 Как обновлять зависимости

В любом активном проекте надо постоянно следить за обновлением библиотек. IDE умеет подсвечивать для каждого модуля, описанного в блоке dependencies {}, наличие новых стабильных версий в репозиториях:

Но этот инструмент работает только для зависимостей, описанных строковыми литералами в build-скриптах, а если мы попытаемся использовать способ с композитными сборками, buildSrc или extra properties, то IDE перестанет нам помогать. Кроме того, визуально просматривать build-скрипты в модулях, для того чтобы сделать обновление библиотек, на мой взгляд, не очень удобно.

Но есть решение — использовать gradle-versions-plugin. Для этого просто применяем плагин к корневому проекту и регистрируем task для проверки новых версий зависимостей. Этот task надо настроить, передав ему лямбду для определения нестабильных версий:

fun isNonStable(version: String): Boolean {
    val stableKeyword = listOf("RELEASE", "FINAL", "GA").any { version.toUpperCase().contains(it) }
    val regex = "^[0-9,.v-]+(-r)?$".toRegex()
    val isStable = stableKeyword || regex.matches(version)
    return isStable.not()
}

tasks.withType<DependencyUpdatesTask> {
    rejectVersionIf {
        isNonStable(candidate.version) && !isNonStable(currentVersion)
    }
}

Теперь запуск команды ./gradlew dependencyUpdates выведет список зависимостей, для которых есть новые версии:

The following dependencies have later milestone versions:
 - androidx.constraintlayout:constraintlayout [2.0.1 -> 2.0.4]
     http://tools.android.com
 - androidx.core:core-ktx [1.5.0-alpha05 -> 1.5.0-beta03]
     https://developer.android.com/jetpack/androidx/releases/core#1.5.0-beta03
 - androidx.fragment:fragment-ktx [1.3.0-beta02 -> 1.3.1]
     https://developer.android.com/jetpack/androidx/releases/fragment#1.3.1
 - androidx.lifecycle:lifecycle-runtime-ktx [2.2.0 -> 2.3.0]
     https://developer.android.com/jetpack/androidx/releases/lifecycle#2.3.0
 - com.github.ben-manes:gradle-versions-plugin [0.36.0 -> 0.38.0]
 - com.github.ben-manes.versions:com.github.ben-manes.versions.gradle.plugin [0.36.0 -> 0.38.0]
 - com.github.bumptech.glide:glide [4.11.0 -> 4.12.0]
     https://github.com/bumptech/glide

#6 Старайтесь не использовать feature-флаги в build config

Во многих проектах release, debug и другие сборки отличаются по функциональности. Например, в отладочных сборках могут быть включены какие-то логи, мониторинг сетевого трафика через прокси, debug menu для смены окружений и т.д. И часто для реализации такого используют флаги, прописанные в build config, например:

android {
    buildTypes {
        getByName("debug") {
            buildConfigField("Boolean", "ENABLE_DEBUG_SCREEN", "true")
        }
        getByName("release") {
            buildConfigField("Boolean", "ENABLE_DEBUG_SCREEN", "false")
        }
    }
}

А дальше такие флаги используются в коде приложения:

if (BuildConfig.ENABLE_DEBUG_SCREEN) {

} else {

}

И у такого решения есть недостатки. Довольно легко перепутать значения флагов и ветки if/else: if (enabled) {} else {} или if (disabled) {} else {}. Именно так однажды, во время рефакторинга, я случайно отправил в релиз то, что должно было включаться только в сборках для QA-отдела (думаю, у многих были похожие истории). Тогда проблему обнаружили оперативно, мы перевыпустили сборку в маркет. Кроме того, недостижимый код может быть скомпилирован и попасть в релиз (здесь я не буду рассуждать о том, что «мертвый» код может вырезаться из итогового приложения). Ну и многим известно, что любые операторы ветвления лучше заменять полиморфизмом. И в Gradle есть статический полиморфизм.

Вместо флагов можно использовать разные source set для различных build variant ("src/release/java ...", "src/debug/java ..."). А если такой код хочется вынести в отдельные модули, то можно использовать специальные конфигурации: debugImplementation, releaseImplementation и т.д. Тогда мы сможем написать код с одним и тем же интерфейсом, но разной реализацией для различных типов сборок.

Например, мы можем выделить debug menu в отдельный модуль и подключать его только для debug и QA-сборок:

dependencies {
    val qaImplementation by configurations

    debugImplementation(project(":feature-debug-screen"))
    qaImplementation(project(":feature-debug-screen"))
}

А stub реализацию для релизной сборки можно реализовать через source set.

#7 Несколько слов про базовую структуру проекта

Совет немного не по теме, но я решил добавить его как часть своего опыта, так как модуляризация напрямую связана с Gradle.

Если для крупных проектов модуляризация кажется вполне очевидным решением, то не совсем понятно, как стоит поступать при старте небольших проектов или когда невозможно предсказать дальнейшее развитие кодовой базы продукта. Нужно ли выделять какие-то модули или достаточно начать с монолита? Я бы, помимо app модуля с основным приложением, всегда выделял как минимум два отдельных модуля:

• UI kit: стили, кастомные элементы управления, виджеты и т.д. Обычно элементы управления на всех экранах приложения делаются консистентно в одном стиле (а возможно, у вас целая дизайн-система), и если в какой-то момент захочется выделить feature-модуль, то он также будет опираться на единый UI kit. Заранее подготовленный модуль с элементами управления и стилями упростит задачу и не потребует значительного рефакторинга приложения.
• Common / utils: все утилитные классы и любые решения, которые не только потребуются в нескольких модулях, но и могут даже копироваться из проекта в проект. Особенно в контексте аутсорса такой модуль будет удобным при старте новых проектов. При вынесении классов в отдельный модуль, а не пакет, можно быть уверенным, что в его коде не окажется каких-либо бизнес сущностей конкретного приложения. Потенциально такой модуль может стать полноценной библиотекой, опубликованной в репозиторий.

#8 Не забывайте про matchingFallbacks

Часто, помимо debug и release, мы создаем и другие типы сборок, например, qa для тестов. И при создании модулей в приложении необязательно их прописывать в каждом build-скрипте. Достаточно при создании своего build type указать в модуле основного приложения те build type, которые следует выбирать при отсутствии каких-то конкретных:

android {
    buildTypes {
        create("qa") {
            setMatchingFallbacks("debug", "release") // если не найдется qa, то искать сначала debug, затем release
        }
    }
}

#9 Убирайте ненужные build variant

Build variant формируются из всех возможных сочетаний product flavor и build type. Возьмем небольшой синтетический пример: создадим три build type – debug (отладочная сборка), release (сборка в маркет) и qa (сборка для тестирования), а во flavor вынесем разные сервера, на которые может смотреть сборка, – production и staging (тестовое окружение). Возможные build variant будут выглядеть так:

Очевидно, что сборка в маркет, которая будет смотреть на тестовое окружение, совершенно бессмысленна и не нужна (stagingRelease). И чтобы исключить ее, можно добавить variant filter:

android {
    variantFilter {
        if (name == "stagingRelease") {
            setIgnore(true)
        }
    }
}

#10 В некоторых модулях, завязанных на Android Framework, можно не использовать Android Gradle Plugin

Если какой-то из ваших модулей завязан на классы из Android Framework, то вовсе не обязательно сразу применять к нему Android Gradle Plugin и писать там файл манифеста. Модули с AGP — более тяжеловесные, чем чистые java/kotlin модули, так как при сборке будут объединяться манифесты, ресурсы и т.д. Когда вам всего лишь требуется для компиляции модуля что-то вроде классов Activity, Context и т.д., то можно просто добавить Android Framework как зависимость:

dependencies {
    compileOnly("com.google.android:android:4.1.1.4")
}

#11 Как написать Gradle-плагин для CI на примере gitlab

Настройка CI — отдельная большая тема, которая потянет на целую увесистую статью. Но я решил немного коснуться её и рассказать, как при помощи написания Gradle-плагина настроить версионирование сборок. Возможно, этот совет поможет тем, кто только поднимает CI, но не знает, как лучше это сделать.

Задача — сделать так, чтобы в сборках на CI versionCode ставился автоматически и представлял из себя последовательные номера 1, 2, 3 и т.д. Я встречал в своей практике, когда в качестве versionCode брался CI job id или каким-то образом использовался timestamp. В таких случаях versionCode с каждой новой версией повышался и был уникальным, но семантически такие версии выглядели достаточно странно.

Основная идея проста — нужно хранить номер будущего релиза где-то во внешнем источнике, куда имеет доступ только сборка, выполняемая на CI. А после каждой успешной публикации нужно инкрементировать этот номер и перезаписывать (нам важно, чтобы сборка не просто успешно выполнилась, но и полученные артефакты распространились для тестировщиков). Стоит оговориться, что такое решение не позволит корректно делать одновременно несколько сборок. Всю эту логику достаточно просто оформить в Gradle-плагин. Как мы уже выяснили, плагины лучше писать, используя композитные сборки.

В случае использования Gitlab CI подставляемый versionCode можно хранить в переменной окружения Gitlab. В его API есть метод для обновления переменных окружения: PUT /projects/:id/variables/:key. Для авторизации используем или project access token, или personal access token для старых версий gitlab.

Расписал добавление такого плагина по шагам, чтобы показать, насколько это просто.

Шаг 1: в настройках проекта на gitlab создать переменные окружения

Нам понадобятся переменные VERSION_CODE_NEXT для хранения номера версии и токен для доступа к API gitlab:

Шаг 2: создать композитную сборку

Добавим в корне проекта директорию ./includedBuilds/ci, а в ней файл build.gradle.kts:

plugins {
    `kotlin-dsl`
}

kotlinDslPluginOptions {
    experimentalWarning.set(false)
}

repositories {
    jcenter()
    google()
}

dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.9.0")
}

gradlePlugin {
    plugins {
        register("gitlab-ci") {
            id = "gitlab-ci"
            implementationClass = "com.redmadrobot.app.ci.CIPlugin" // Этот плагин создадим в следующих шагах
        }
    }
}

Рядом создадим пустой файл ./includedBuilds/ci/settings.gradle.kts, если этого не сделать, то у вас сломается clean проекта.

В корневом проекте в файл settings.gradle.kts добавим строку includeBuild("includedBuilds/ci").

Шаг 3: написать плагин

Так будет выглядеть метод для получения versionCode, его можно будет использовать в build-скрипте (можно добавить в любой файл: при применении плагина код будет скомпилирован и добавлен в classpath build-скрипта):

const val GITLAB_VARIABLE_NEXT_VERSION = "VERSION_CODE_NEXT"
private const val DEFAULT_VERSION_CODE = 1

fun getVersionCode(): Int = if (isRunningOnCi()) {
    getNextVersionCode()
} else {
    DEFAULT_VERSION_CODE
}

private fun isRunningOnCi(): Boolean = System.getenv()["CI"] != null

private fun getNextVersionCode(): Int {
    return System.getenv()[GITLAB_VARIABLE_NEXT_VERSION]?.toInt()
        ?: error("$GITLAB_VARIABLE_NEXT_VERSION must be specified")
}

Примерно так можно написать метод для обновления переменной на gitlab:

fun updateGitlabVariable(variable: String, value: String) {
    val projectId = System.getenv()["CI_PROJECT_ID"]
    val accessToken = System.getenv()["TOKEN_FOR_GITLAB_API"]

    val client = OkHttpClient()

    val body = MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("value", value)
        .build()

    val request = Request.Builder()
        .header("PRIVATE-TOKEN", accessToken)
        .url("https://gitlab.com/api/v4/projects/$projectId/variables/$variable")
        .method("PUT", body)
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Couldn't update variable”)
    }
}

Далее пишем task, который при выполнении будет инкрементировать версию:

open class IncrementVersionCode : DefaultTask() {

    @TaskAction
    fun action() {
        val nextVersionCode = getDistributionVersionCode() + 1
        updateGitlabVariable(
            GITLAB_VARIABLE_NEXT_VERSION,
            nextVersionCode.toString()
        )
    }
}

И напишем плагин, который добавит task в проект:

package com.redmadrobot.app.ci

import org.gradle.api.Plugin
import org.gradle.api.Project

class CIPlugin : Plugin<Project> {

    override fun apply(target: Project) {
        target.tasks.register("incrementVersionCode", IncrementVersionCode::class.java)
    }
}

Шаг 4: подключить плагин

В build-скрипте проекта, из которого собирается apk, добавим следующие строки:

plugins {
    id("gitlab-ci")
}

android {
    defaultConfig {
        versionCode = com.redmadrobot.app.ci.getVersionCode()
    }
}

project.afterEvaluate {
    tasks["incrementVersionCode"].mustRunAfter( // Обновление должно происходить только после публикации сборки в Firebase App Distribution
        tasks["appDistributionUploadRelease"],
        tasks["appDistributionUploadQa"]
    )
}

Теперь команда ./gradlew assembleRelease appDistributionUploadRelease incrementVersionCode будет делать новую сборку, публиковать ее и инкрементировать версию. Остается добавить эту команду на нужный триггер в ваш скрипт в .gitlab-ci.yml.

В заключение

Думаю, что у многих есть свои best practices по работе с Gradle, которыми вы бы могли поделиться с сообществом. Или что-то описанное в этой статье можно сделать лучше. Так что буду рад увидеть ваши советы в комментариях.

Что ещё посмотреть

Мне очень помогли доклады про работу с Gradle, которые делал Степан Гончаров в разные годы. Ссылки на них, если кому-то интересна эта тема:

• Gradle pipeline optimisation: Beyond basics;
• Gradle от A до Я;
• Абсолютная модуляризация.

И в формате дискуссии: Разбор доклада Степана Гончарова «Gradle от А до Я»