Система сборки Gradle в Android Studio позволяет включать в сборку внешние двоичные файлы или другие библиотечные модули в качестве зависимостей. Зависимости могут находиться на вашем компьютере или в удаленном репозитории, и любые объявленные ими транзитивные зависимости также автоматически включаются. На этой странице описано, как использовать зависимости в вашем проекте Android, включая сведения о поведении и конфигурациях, специфичных для плагина Android Gradle (AGP). Для более глубокого концептуального руководства по зависимостям Gradle вам также следует просмотреть руководство Gradle по управлению зависимостями , но помните, что ваш проект Android должен использовать только конфигурации зависимостей , определенные на этой странице.
Добавьте зависимость библиотеки или плагина
Лучший способ добавлять зависимости сборки и управлять ими — использовать каталоги версий, метод, который новые проекты используют по умолчанию. В этом разделе рассматриваются наиболее распространенные типы конфигураций, используемые в проектах Android; дополнительные параметры см. в документации Gradle . Пример приложения, использующего каталоги версий, см. в разделе «Теперь в Android» . Если у вас уже настроены зависимости сборки без каталогов версий и у вас многомодульный проект, мы рекомендуем выполнить миграцию .
Рекомендации по добавлению и управлению собственными зависимостями (не распространенными) см. в разделе «Нативные зависимости» .
В следующем примере мы добавляем в наш проект удаленную двоичную зависимость ( библиотеку Jetpack Macrobenchmark ), зависимость модуля локальной библиотеки ( myLibrary
) и зависимость плагина (плагин Android Gradle). Вот общие шаги по добавлению этих зависимостей в ваш проект:
Добавьте псевдоним для нужной версии зависимости в разделе
[versions]
файла каталога версий с именемlibs.versions.toml
(в каталогеgradle
в представлении Project или 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».Добавьте псевдоним для зависимости в разделах
[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), в которой группируются семейства библиотек и их версии. Вы можете включить спецификацию в свой каталог версий и файлы сборки и позволить ей управлять этими версиями за вас. Подробности см. в разделе «Использование спецификации» .
Добавьте ссылку на псевдоним зависимости в сценарий сборки модулей, которым требуется зависимость. Преобразуйте подчеркивания и тире псевдонима в точки, когда вы ссылаетесь на него из сценария сборки. Наш сценарий сборки на уровне модуля будет выглядеть так:
Котлин
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 | Gradle добавляет зависимость в путь к классам компиляции и выходные данные сборки. Когда модуль включает зависимость api , он сообщает Gradle, что модуль хочет транзитивно экспортировать эту зависимость в другие модули, чтобы она была доступна им как во время выполнения, так и во время компиляции. Используйте эту конфигурацию с осторожностью и только с зависимостями, которые необходимо транзитивно экспортировать другим восходящим потребителям. Если зависимость |
compileOnly | Gradle добавляет зависимость только к пути к классам компиляции (то есть она не добавляется в выходные данные сборки). Это полезно, когда вы создаете модуль Android и вам нужна зависимость во время компиляции, но необязательно, чтобы она присутствовала во время выполнения. Например, если вы зависите от библиотеки, которая включает только аннотации времени компиляции — обычно используемые для генерации кода, но часто не включенные в выходные данные сборки — вы можете пометить эту библиотеку compileOnly .Если вы используете эту конфигурацию, ваш библиотечный модуль должен включать условие времени выполнения, чтобы проверить, доступна ли зависимость, а затем корректно изменить его поведение, чтобы он продолжал работать, даже если он не указан. Это помогает уменьшить размер конечного приложения за счет отсутствия добавления временных зависимостей, которые не являются критическими. Примечание. Конфигурацию |
runtimeOnly | Gradle добавляет зависимость только к выходным данным сборки для использования во время выполнения. То есть он не добавляется в путь к классам компиляции. Это редко используется в Android, но обычно используется в серверных приложениях для реализации журналирования. Например, библиотека может использовать API ведения журналов, который не включает реализацию. Потребители этой библиотеки могут добавить ее в качестве зависимости implementation и включить зависимость runtimeOnly для фактической реализации ведения журнала. |
ksp | Эти конфигурации предоставляют библиотеки, которые обрабатывают аннотации и другие символы в вашем коде перед его компиляцией. Обычно они проверяют ваш код или генерируют дополнительный код, сокращая объем кода, который вам нужно написать. Чтобы добавить такую зависимость, необходимо добавить ее в путь к классам процессора аннотаций, используя конфигурации Плагин Android Gradle предполагает, что зависимость является обработчиком аннотаций, если его JAR-файл содержит следующий файл: Если плагин обнаруживает обработчик аннотаций, находящийся в пути к классам компиляции, он выдает ошибку сборки. Принимая решение о том, какую конфигурацию использовать, учитывайте следующее:
Дополнительные сведения об использовании обработчиков аннотаций см. в разделе Добавление обработчиков аннотаций . |
lintChecks | Используйте эту конфигурацию, чтобы включить библиотеку, содержащую проверки lint, которые Gradle должен выполнять при создании проекта приложения для Android. Обратите внимание, что файлы AAR, содержащие файл |
lintPublish | Используйте эту конфигурацию в проектах библиотеки Android, чтобы включить проверки lint, которые Gradle должен скомпилировать в файл lint.jar и упаковать в свой AAR. Это приводит к тому, что проекты, использующие ваш AAR, также применяют эти проверки. Если вы ранее использовали конфигурацию зависимостей lintChecks для включения проверок 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
Тогда порядок плоской зависимости будет следующим:
-
LIB_A
-
LIB_D
-
LIB_B
-
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 в индексе Google Play SDK при возникновении следующих проблем:
- SDK помечены их авторами как устаревшие.
- SDK нарушают правила Google Play.
Предупреждения являются сигналами о том, что вам следует обновить эти зависимости, поскольку использование устаревших версий может помешать вам публиковать их в консоли Google Play в будущем.
Добавить зависимости сборки без каталогов версий
Мы рекомендуем использовать каталоги версий для добавления зависимостей и управления ими, но простым проектам они могут не понадобиться. Вот пример файла сборки, который не использует каталоги версий:
Котлин
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' }