Добавление зависимостей

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

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

Лучший способ добавлять зависимости сборки и управлять ими – использовать каталоги версий. Этот метод по умолчанию применяется в новых проектах. В этом разделе рассматриваются наиболее распространенные типы конфигураций, используемые для проектов для Android. Дополнительные варианты см. в документации Gradle. Пример приложения, в котором используются каталоги версий, можно найти в статье Now in Android. Если у вас уже настроены зависимости сборки без каталогов версий и у вас многомодульный проект, рекомендуем выполнить миграцию.

Инструкции по добавлению нативных зависимостей и управлению ими (нечасто) см. в разделе Нативные зависимости.

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

1. Добавьте псевдоним для нужной версии зависимости в разделе [versions] файла каталога версий libs.versions.toml (в каталоге gradle в представлении Project (Проект) или Gradle Scripts (Скрипты Gradle) в представлении 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), которая группирует семейства библиотек и их версии. Вы можете включить BOM в каталог версий и файлы сборки, чтобы управлять версиями. Подробнее об использовании спецификации…

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

   Kotlin

   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.

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 и сохраняются в блоке подписи вашего приложения. Мы рекомендуем не удалять этот файл, чтобы обеспечить безопасность и удобство пользователей. Чтобы отказаться от этого, добавьте в файл build.gradle.kts модуля блок dependenciesInfo.

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

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

Статистика SDK

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

• Авторы пометили эти SDK как устаревшие.
• SDK нарушают правила Google 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'
}