Настройте свою сборку

Система сборки Android компилирует ресурсы приложения и исходный код, а затем упаковывает их в APK-файлы или пакеты приложений Android, которые можно тестировать, развертывать, подписывать и распространять.

В обзоре сборки Gradle и структуре сборки Android мы обсудили концепции сборки и структуру Android-приложения. Теперь пришло время настроить сборку.

Глоссарий сборок Android

Gradle и плагин Android Gradle помогут вам настроить следующие аспекты сборки:

Типы постройки

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

Например, тип сборки debug включает параметры отладки и подписывает приложение ключом отладки, в то время как тип сборки release может уменьшить размер, зашифровать и подписать ваше приложение ключом release для распространения.

Для сборки приложения необходимо определить как минимум один тип сборки. Android Studio по умолчанию создает типы сборки debug и release. Чтобы начать настройку параметров упаковки для вашего приложения, узнайте, как настроить типы сборки .

Вкусы продуктов
Варианты продукта представляют собой различные версии вашего приложения, которые вы можете выпустить для пользователей, например, бесплатную и платную версии. Вы можете настраивать варианты продукта, используя различный код и ресурсы, при этом совместно используя и повторно применяя части, общие для всех версий вашего приложения. Варианты продукта являются необязательными и должны создаваться вручную. Чтобы начать создавать различные версии вашего приложения, узнайте, как настроить варианты продукта .
Варианты сборки
Вариант сборки — это результат взаимодействия типа сборки и варианта продукта, и именно эту конфигурацию Gradle использует для сборки вашего приложения. Используя варианты сборки, вы можете собирать отладочную версию вариантов продукта во время разработки и подписанные релизные версии вариантов продукта для распространения. Хотя вы не настраиваете варианты сборки напрямую, вы настраиваете типы сборки и варианты продукта, которые их формируют. Создание дополнительных типов сборки или вариантов продукта также создает дополнительные варианты сборки. Чтобы узнать, как создавать и управлять вариантами сборки, ознакомьтесь с обзором «Настройка вариантов сборки» .
Манифестные записи
В конфигурации варианта сборки можно указать значения для некоторых свойств файла манифеста. Эти значения переопределяют существующие значения в файле манифеста. Это полезно, если вы хотите создать несколько вариантов вашего приложения с разным именем приложения, минимальной версией SDK или целевой версией SDK. При наличии нескольких манифестов инструмент объединения манифестов объединяет их настройки .
Зависимости
Система сборки управляет зависимостями проекта как из локальной файловой системы, так и из удаленных репозиториев. Это означает, что вам не нужно вручную искать, загружать и копировать бинарные пакеты зависимостей в каталог вашего проекта. Для получения дополнительной информации см. раздел «Добавление зависимостей сборки» .
Подписание
Система сборки позволяет указывать параметры подписи в конфигурации сборки и может автоматически подписывать ваше приложение в процессе сборки. Система сборки подписывает отладочную версию с помощью ключа и сертификата по умолчанию, используя известные учетные данные, чтобы избежать запроса пароля во время сборки. Система сборки не подписывает релизную версию, если вы явно не определите конфигурацию подписи для этой сборки. Если у вас нет ключа для релиза, вы можете сгенерировать его, как описано в разделе «Подпишите ваше приложение» . Подписанные релизные сборки необходимы для распространения приложений через большинство магазинов приложений.
Сокращение кода и ресурсов
Система сборки позволяет указывать отдельный файл правил ProGuard для каждого варианта сборки. При сборке приложения система применяет соответствующий набор правил для уменьшения размера кода и ресурсов с помощью встроенных инструментов уменьшения размера, таких как R8. Уменьшение размера кода и ресурсов может помочь снизить размер APK или AAB-файла.
Поддержка нескольких APK-файлов
Система сборки позволяет автоматически создавать различные APK-файлы, каждый из которых содержит только код и ресурсы, необходимые для определенной плотности экрана или интерфейса двоичного кода приложения (ABI). Дополнительную информацию см. в разделе «Создание нескольких APK-файлов ». Однако рекомендуется использовать единый AAB, поскольку он обеспечивает разделение по языку в дополнение к плотности экрана и ABI, избегая при этом необходимости загрузки нескольких артефактов в Google Play. Все новые приложения, отправленные после августа 2021 года, должны использовать AAB.

Версии Java в сборках Android

Независимо от того, написан ли ваш исходный код на Java, Kotlin или на обоих языках, в нескольких местах вам необходимо выбрать версию языка JDK или Java для сборки. Подробнее см. раздел «Версии Java в сборках Android» .

Соберите файлы конфигурации

Для создания пользовательских конфигураций сборки необходимо внести изменения в один или несколько файлов конфигурации сборки. Эти текстовые файлы используют предметно-ориентированный язык (DSL) для описания и управления логикой сборки с помощью скрипта Kotlin , который является разновидностью языка Kotlin. Также для настройки сборок можно использовать Groovy , динамический язык для виртуальной машины Java (JVM).

Для начала настройки сборки вам не нужно знать Kotlin Script или Groovy, поскольку плагин Android Gradle предоставляет большинство необходимых элементов DSL. Чтобы узнать больше о DSL плагина Android Gradle, ознакомьтесь с документацией по DSL . Kotlin Script также использует базовый DSL Kotlin в Gradle.

При создании нового проекта Android Studio автоматически создает некоторые из этих файлов и заполняет их на основе разумных значений по умолчанию. Обзор созданных файлов см. в разделе «Структура сборки Android» .

Файл-оболочка Gradle

Gradle-оболочка ( gradlew ) — это небольшое приложение, входящее в состав исходного кода, которое загружает и запускает сам Gradle. Это обеспечивает более согласованное выполнение сборки. Разработчики загружают исходный код приложения и запускают gradlew . Это загружает необходимую дистрибуцию Gradle и запускает Gradle для сборки вашего приложения.

В файле gradle/wrapper/gradle-wrapper.properties содержится свойство distributionUrl , описывающее, какая версия Gradle используется для запуска сборки.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Файл настроек Gradle

Файл settings.gradle.kts (для Kotlin DSL) или settings.gradle (для Groovy DSL) находится в корневом каталоге проекта. Этот файл настроек определяет параметры репозитория на уровне проекта и сообщает Gradle, какие модули следует включать при сборке вашего приложения. В многомодульных проектах необходимо указать каждый модуль, который должен быть включен в финальную сборку.

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

Котлин 

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Классный 

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

Файл сборки верхнего уровня

Файл build.gradle.kts (для Kotlin DSL) или build.gradle (для Groovy DSL) находится в корневом каталоге проекта. Обычно он определяет общие версии плагинов, используемых модулями в вашем проекте.

Приведённый ниже пример кода описывает настройки по умолчанию и элементы DSL в скрипте сборки верхнего уровня после создания нового проекта:

Котлин 

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "9.4.0" apply false
    id("com.android.library") version "9.4.0" apply false
    id("org.jetbrains.kotlin.android") version "2.4.10" apply false
}

Классный 

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '9.4.0' apply false
    id 'com.android.library' version '9.4.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.4.10' apply false
}

Файл сборки на уровне модуля

Файл build.gradle.kts (для Kotlin DSL) или build.gradle (для Groovy DSL) на уровне модуля находится в каждом project / module / каталоге. Он позволяет настраивать параметры сборки для конкретного модуля, в котором он расположен. Настройка этих параметров сборки позволяет задавать пользовательские параметры упаковки, такие как дополнительные типы сборки и варианты продукта, а также переопределять настройки в main/ манифесте приложения или скрипте сборки верхнего уровня.

Настройки Android SDK

Файл сборки на уровне модуля для вашего приложения содержит настройки, указывающие версии Android SDK, используемые при компиляции, выбор поведения платформы и указание минимальной версии, на которой работает ваше приложение.

Обзор спецификаций SDK в сборке Gradle
Рисунок 1. Android SDK в сборке
compileSdk

compileSdk определяет, какие API Android и Java доступны при компиляции исходного кода. Чтобы использовать новейшие функции Android, используйте последнюю версию Android SDK при компиляции.

Некоторые API платформы Android могут быть недоступны на более старых уровнях API. Вы можете условно защитить использование более новых функций или использовать библиотеки совместимости AndroidX для использования более новых функций с более низкими уровнями API Android.

Каждый Android SDK предоставляет подмножество Java API для использования в вашем приложении. В таблице «Какие Java API я могу использовать в своем исходном коде Java или Kotlin?» показано, какой уровень Java API доступен в зависимости от версии Android SDK. Более новые Java API поддерживаются в более ранних версиях Android через десахаризацию , которую необходимо включить в сборке.

Если вам необходимо скомпилировать код для определенного дополнительного уровня API, используйте расширенный синтаксис блока compileSdk и укажите minorApiLevel :

Котлин 

    android {
        compileSdk {
            version = release(36) {
                minorApiLevel = 1
            }
        }
    }

Классный 

    android {
        compileSdk {
            version = release(36) {
                minorApiLevel = 1
            }
        }
    }

Android Studio выдает предупреждения, если ваш compileSdk конфликтует с текущей версией Android Studio, AGP или требованиями к зависимостям библиотек вашего проекта.

minSdk

Параметр minSdk указывает самую низкую версию Android, которую вы хотите поддерживать своим приложением. Установка параметра minSdk ограничивает устройства, на которые можно установить ваше приложение.

Поддержка более старых версий Android может потребовать добавления большего количества условных проверок в код или более широкого использования библиотек совместимости AndroidX. Вам следует сопоставить затраты на поддержку более старых версий с процентом пользователей, которые все еще используют эти старые версии. Текущие проценты использования версий можно посмотреть в таблице версий в мастере создания нового проекта Android Studio.

При редактировании кода в Android Studio или выполнении проверок во время сборки, lint будет предупреждать об используемых вами API, которые недоступны в minSdk . Вам следует исправить это, сделав новые функции условными или используя Appcompat для обратной совместимости.

targetSdk

targetSdk выполняет две функции:

  1. Это определяет поведение вашего приложения во время выполнения.
  2. Это подтверждает, с какой версией Android вы проводили тестирование.

Если вы используете устройство с более высокой версией Android, чем указанная в targetSdk , Android запускает ваше приложение в режиме совместимости, который ведет себя аналогично более низкой версии, указанной в targetSdk . Например, когда в API 23 была введена модель разрешений во время выполнения, не все приложения были готовы сразу же ее использовать. Установив targetSdk на 22, эти приложения могли работать на устройствах с API 23 без использования разрешений во время выполнения и могли использовать функции, включенные в последнюю версию compileSdk . Политика распространения Google Play применяет дополнительные правила на уровне целевого API .

Значение