Добавить зависимости сборки

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

Система сборки Gradle в Android Studio позволяет включать внешние бинарные файлы или другие библиотечные модули в сборку в качестве зависимостей. Зависимости могут располагаться на вашем компьютере или в удаленном репозитории, и любые объявленные ими транзитивные зависимости также автоматически включаются. На этой странице описывается, как использовать зависимости в вашем проекте Android, включая подробности о поведении и конфигурациях, специфичных для плагина Android Gradle (AGP). Более подробное руководство по зависимостям Gradle см. в руководстве Gradle по управлению зависимостями , но помните, что ваш проект Android должен использовать только конфигурации зависимостей, определенные на этой странице.

Внимание: при указании зависимостей не следует использовать динамические номера версий, например, 'com.android.tools.build:gradle:3.+' . Использование этой функции может привести к неожиданным обновлениям версий, трудностям с разрешением различий в версиях и снижению производительности.

Добавьте зависимость от библиотеки или плагина.

Лучший способ добавлять и управлять зависимостями сборки — использовать каталоги версий, метод, который новые проекты используют по умолчанию. В этом разделе рассматриваются наиболее распространенные типы конфигураций, используемые для проектов Android; для получения дополнительных параметров обратитесь к документации Gradle . Пример приложения, использующего каталоги версий, см. в разделе «Теперь в Android» . Если у вас уже настроены зависимости сборки без каталогов версий и у вас многомодульный проект, мы рекомендуем выполнить миграцию .

Рекомендации по добавлению и управлению собственными зависимостями (что встречается нечасто) см. в разделе «Собственные зависимости» .

В следующем примере мы добавляем в наш проект удаленную бинарную зависимость ( библиотеку Jetpack Macrobenchmark ), локальную зависимость модуля библиотеки ( myLibrary ) и зависимость плагина (плагин Android Gradle). Вот общие шаги для добавления этих зависимостей в ваш проект:

Примечание: Каталоги версий можно указать в файле настроек , но мы рекомендуем использовать отдельный файл toml для более эффективной поддержки подсказок кода и подсветки синтаксиса в Android Studio.

1. Добавьте псевдоним для нужной версии зависимости в раздел [versions] файла каталога версий, назвав его libs.versions.toml (в каталоге gradle в представлении проекта или в Gradle Scripts в представлении Android ):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Псевдонимы могут содержать дефисы или подчеркивания. Эти псевдонимы генерируют вложенные значения, на которые можно ссылаться в скриптах сборки. Ссылки начинаются с имени каталога, части libs файла libs.versions.toml . При использовании каталога с одной версией мы рекомендуем оставить значение по умолчанию "libs".

2. Добавьте псевдоним для зависимости в разделы [libraries] (для удаленных исполняемых файлов или локальных модулей библиотек) или [plugins] (для плагинов) файла libs.versions.toml .

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Некоторые библиотеки доступны в опубликованной спецификации (BOM), которая группирует семейства библиотек и их версии. Вы можете включить спецификацию в свой каталог версий и файлы сборки, и позволить ей управлять этими версиями за вас. Подробнее см. раздел «Использование спецификации» .

3. Добавьте ссылку на псевдоним зависимости в скрипт сборки модуля (модулей), который (которые) требует эту зависимость. Преобразуйте подчеркивания и дефисы в псевдониме в точки при ссылке из скрипта сборки. Наш скрипт сборки на уровне модуля будет выглядеть так:

   Котлин

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Классный

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Ссылки на плагины включают в себя упоминание plugins после имени каталога, а ссылки на версии включают в себя versions после имени каталога (упоминание версий встречается редко; см. раздел «Зависимости с одинаковыми номерами версий » для примеров ссылок на версии). Ссылки на библиотеки не содержат квалификатора libraries , поэтому вы не можете использовать versions или plugins в начале псевдонима библиотеки.

Настройка зависимостей

Внутри блока dependencies вы можете объявить зависимость от библиотеки, используя одну из нескольких различных конфигураций зависимостей (например, как implementation ранее). Каждая конфигурация зависимости предоставляет Gradle различные инструкции о том, как использовать зависимость. В следующей таблице описаны все конфигурации, которые вы можете использовать для зависимости в вашем проекте Android.

Конфигурация	Поведение
implementation	Gradle добавляет зависимость в путь к классам компиляции и упаковывает её в выходные данные сборки. Когда ваш модуль настраивает зависимость implementation , он сообщает Gradle, что вы не хотите, чтобы модуль передавал эту зависимость другим модулям во время компиляции. То есть, зависимость не становится доступной для других модулей, которые зависят от текущего модуля. Использование этой конфигурации зависимостей вместо api может значительно сократить время сборки, поскольку уменьшает количество модулей, которые система сборки должна перекомпилировать. Например, если зависимость implementation меняет свой API, Gradle перекомпилирует только эту зависимость и модули, которые непосредственно от нее зависят. Большинство модулей приложений и тестов должны использовать эту конфигурацию.
api	Gradle добавляет зависимость в путь к классам компиляции и в выходные данные сборки. Когда модуль включает зависимость api , это означает, что модуль хочет транзитивно экспортировать эту зависимость в другие модули, чтобы она была доступна им как во время выполнения, так и во время компиляции. Используйте эту конфигурацию с осторожностью и только с зависимостями, которые вам необходимо транзитивно экспортировать другим вышестоящим потребителям. Если зависимость api изменяет свой внешний API, Gradle перекомпилирует все модули, имеющие доступ к этой зависимости, во время компиляции. Большое количество зависимостей api может значительно увеличить время сборки. Если вы не хотите предоставлять доступ к API зависимости отдельному модулю, библиотечные модули должны использовать зависимости implementation .
compileOnly	Gradle добавляет зависимость только в путь компиляции (то есть, она не добавляется в выходные данные сборки). Это полезно при создании модуля Android, когда зависимость необходима во время компиляции, но её наличие во время выполнения необязательно. Например, если вы зависите от библиотеки, которая содержит только аннотации времени компиляции — обычно используемые для генерации кода, но часто не включаемые в выходные данные сборки — вы можете пометить эту библиотеку compileOnly . При использовании этой конфигурации ваш библиотечный модуль должен включать условие во время выполнения для проверки доступности зависимости, а затем корректно изменять свое поведение, чтобы он мог продолжать функционировать, даже если зависимость не предоставлена. Это помогает уменьшить размер конечного приложения, избегая добавления временных зависимостей, которые не являются критически важными. Примечание: Вы не можете использовать конфигурацию compileOnly с зависимостями Android Archive (AAR).
runtimeOnly	Gradle добавляет зависимость только в выходные данные сборки для использования во время выполнения. То есть, она не добавляется в путь к классам компиляции. Это редко используется в Android, но часто применяется в серверных приложениях для предоставления реализаций логирования. Например, библиотека может использовать API логирования, который не включает реализацию. Пользователи этой библиотеки могут добавить её в качестве зависимости implementation и включить зависимость runtimeOnly для фактической реализации логирования.
ksp kapt annotationProcessor	Эти конфигурации предоставляют библиотеки, которые обрабатывают аннотации и другие символы в вашем коде перед его компиляцией. Обычно они проверяют ваш код или генерируют дополнительный код, сокращая объем кода, который вам нужно написать. Чтобы добавить такую ​​зависимость, необходимо добавить её в classpath обработчика аннотаций, используя конфигурации ksp , kapt или annotationProcessor . Использование этих конфигураций повышает производительность сборки, разделяя classpath компиляции и classpath обработчика аннотаций. Если Gradle обнаружит обработчики аннотаций в classpath компиляции, он отключит предотвращение компиляции , что негативно скажется на времени сборки (Gradle 5.0 и выше игнорирует обработчики аннотаций, найденные в classpath компиляции). Плагин Android Gradle считает зависимость обработчиком аннотаций, если её JAR-файл содержит следующий файл: META-INF/services/javax.annotation.processing.Processor Если плагин обнаружит обработчик аннотаций, находящийся в пути компиляции, он выдаст ошибку сборки. ksp — это обработчик символов Kotlin, который запускается компилятором Kotlin. kapt и apt — это отдельные инструменты, которые обрабатывают аннотации перед выполнением компиляторов Kotlin или Java. При выборе конфигурации следует учитывать следующее: Если обработчик символов доступен в качестве Kotlin Symbol Processor, используйте его в качестве зависимости ksp . Подробную информацию об использовании Kotlin Symbol Processors см. в разделе «Переход с kapt на ksp» . Если обработчик символов недоступен в качестве обработчика символов Kotlin: Если ваш проект включает исходный код на Kotlin (но может также включать исходный код на Java), используйте kapt для его включения. Если ваш проект использует только исходный код Java, используйте annotationProcessor для его включения. Для получения дополнительной информации об использовании обработчиков аннотаций см. раздел «Добавление обработчиков аннотаций» .
lintChecks	Используйте эту конфигурацию, чтобы включить библиотеку, содержащую проверки синтаксиса, которые Gradle должен выполнять при сборке вашего проекта Android-приложения. Обратите внимание, что AAR-файлы, содержащие файл lint.jar , автоматически запускают проверки, определенные в этом файле; вам не нужно добавлять явную зависимость lint.jar . Это позволяет определять библиотеки и связанные с ними проверки линтинга в одной зависимости, гарантируя, что ваши проверки будут запущены lintChecks когда пользователи будут использовать вашу библиотеку.
lintPublish	Используйте эту конфигурацию в проектах библиотек Android, чтобы включить проверки линтинга, которые вы хотите скомпилировать в файл lint.jar и упаковать в ваш AAR-файл. Это приведет к тому, что проекты, использующие ваш AAR-файл, также будут применять эти проверки линтинга. Если ранее вы использовали конфигурацию зависимости lintChecks для включения проверок линтинга в опубликованный AAR-файл, вам необходимо перевести эти зависимости на использование конфигурации lintPublish . Котлин dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Классный dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Настройте зависимости для конкретного варианта сборки.

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

Например, чтобы добавить удаленную бинарную зависимость только к вашей "бесплатной" версии продукта с помощью конфигурации implementation , используйте следующее:

Котлин

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Классный

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Однако, если вы хотите добавить зависимость для варианта, который сочетает в себе тип продукта и тип сборки, то необходимо инициализировать имя конфигурации:

Котлин

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Классный

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Чтобы добавить зависимости implementation для ваших локальных и инструментальных тестов, это выглядит следующим образом:

Котлин

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Классный

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Однако в данной ситуации некоторые конфигурации не имеют смысла. Например, поскольку другие модули не могут зависеть от androidTest , при использовании конфигурации androidTestApi вы получите следующее предупреждение:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Порядок зависимостей

Порядок перечисления зависимостей указывает на приоритет каждой из них: первая библиотека имеет более высокий приоритет, чем вторая, вторая — выше третьей и так далее. Этот порядок важен в случае слияния ресурсов или элементов манифеста из библиотек в ваше приложение.

Например, если в вашем проекте указано следующее:

• Зависимость от LIB_A и LIB_B (в указанном порядке)
• А LIB_A зависит от LIB_C и LIB_D (в указанном порядке).
• А LIB_B также зависит от LIB_C

В таком случае порядок плоских зависимостей будет следующим:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Это гарантирует, что LIB_A и LIB_B могут переопределить LIB_C ; при этом LIB_D по-прежнему имеет более высокий приоритет, чем LIB_B поскольку LIB_A (которая от него зависит) имеет более высокий приоритет, чем LIB_B .

Для получения дополнительной информации о том, как объединяются манифесты из разных источников/зависимостей проекта, см. раздел «Объединение нескольких файлов манифестов» .

Информация о зависимостях для Play Console

При сборке вашего приложения AGP включает метаданные, описывающие зависимости библиотек, которые компилируются в ваше приложение. При загрузке вашего приложения Play Console проверяет эти метаданные, чтобы выдавать предупреждения об известных проблемах с SDK и зависимостями, используемыми вашим приложением, и в некоторых случаях предоставлять полезную обратную связь для решения этих проблем.

Данные сжимаются, шифруются ключом подписи Google Play и хранятся в блоке подписи вашего релизного приложения. Мы рекомендуем сохранить этот файл зависимостей для обеспечения безопасного и удобного взаимодействия с пользователем. Вы можете отказаться от этого, добавив следующий блок dependenciesInfo в файл build.gradle.kts вашего модуля.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Для получения дополнительной информации о нашей политике и возможных проблемах с зависимостями см. нашу страницу поддержки по использованию сторонних SDK в вашем приложении .

Информация об SDK

В Android Studio отображаются предупреждения линтера в файле каталога версий и в диалоговом окне структуры проекта для общедоступных SDK из индекса SDK Google Play при наличии следующих проблем:

• Авторы пометили SDK как устаревшие.
• Эти SDK нарушают правила Play.
• В комплектах разработки программного обеспечения (SDK) обнаружены известные уязвимости в системе безопасности.
• Разработчики этих SDK объявили их устаревшими.

Эти предупреждения указывают на необходимость обновления указанных зависимостей, поскольку использование устаревших версий может помешать вам публиковать приложение в Google Play Console в будущем.

Добавить зависимости сборки без каталогов версий

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

Котлин

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Классный

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

В этом файле сборки объявляется зависимость от версии 12.3 библиотеки "app-magic" в группе имен "com.example.android". Объявление удаленной бинарной зависимости представляет собой сокращенную запись для следующего:

Котлин

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Классный

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

В файле сборки также указывается зависимость от модуля библиотеки Android с именем "mylibrary"; это имя должно совпадать с именем библиотеки, определенным с помощью include: в файле settings.gradle.kts . При сборке приложения система сборки компилирует модуль библиотеки и упаковывает полученное скомпилированное содержимое в приложение.

Файл сборки также объявляет зависимость от плагина Android Gradle ( com.application.android ). Если у вас несколько модулей, использующих один и тот же плагин, в пути к классам сборки для всех модулей может быть только одна версия плагина. Вместо указания версии в каждом скрипте сборки модуля, следует включить зависимость от плагина в корневой скрипт сборки с указанием версии и указать, что её не следует применять. Добавление apply false указывает Gradle учитывать версию плагина, но не использовать её в корневом скрипте сборки. Обычно корневой скрипт сборки пуст, за исключением этого блока plugins .

Котлин

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Классный

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Если у вас проект с одним модулем, вы можете явно указать версию в скрипте сборки на уровне модуля, а скрипт сборки на уровне проекта оставить пустым:

Котлин

plugins {
    id("com.android.application") version "8.3.0"
}

Классный

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}