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

Система сборки 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 в представлении 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».

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 , он сообщает Gradle, что модуль хочет транзитивно экспортировать эту зависимость в другие модули, чтобы она была доступна им как во время выполнения, так и во время компиляции. Используйте эту конфигурацию с осторожностью и только с зависимостями, которые необходимо транзитивно экспортировать другим восходящим потребителям. Если зависимость api изменяет свой внешний API, Gradle перекомпилирует все модули, имеющие доступ к этой зависимости во время компиляции. Наличие большого количества зависимостей api может значительно увеличить время сборки. Если вы не хотите предоставить API зависимостей отдельному модулю, библиотечные модули должны вместо этого использовать зависимости implementation .
compileOnly	Gradle добавляет зависимость только в путь к классам компиляции (то есть она не добавляется в выходные данные сборки). Это полезно, когда вы создаете модуль Android и вам нужна зависимость во время компиляции, но необязательно, чтобы она присутствовала во время выполнения. Например, если вы зависите от библиотеки, которая включает только аннотации времени компиляции — обычно используемые для генерации кода, но часто не включенные в выходные данные сборки — вы можете пометить эту библиотеку compileOnly . Если вы используете эту конфигурацию, ваш библиотечный модуль должен включать условие времени выполнения, чтобы проверить, доступна ли зависимость, а затем корректно изменить его поведение, чтобы он мог продолжать работать, даже если он не указан. Это помогает уменьшить размер конечного приложения за счет отсутствия добавления временных зависимостей, которые не являются критическими. Примечание. Конфигурацию compileOnly нельзя использовать с зависимостями Android Archive (AAR).
runtimeOnly	Gradle добавляет зависимость только к выходным данным сборки для использования во время выполнения. То есть он не добавляется в путь к классам компиляции. Это редко используется в Android, но обычно используется в серверных приложениях для реализации журналирования. Например, библиотека может использовать API ведения журналов, который не включает реализацию. Потребители этой библиотеки могут добавить ее в качестве зависимости implementation и включить зависимость runtimeOnly для фактической реализации ведения журнала.
ksp kapt annotationProcessor	Эти конфигурации предоставляют библиотеки, которые обрабатывают аннотации и другие символы в вашем коде перед его компиляцией. Обычно они проверяют ваш код или генерируют дополнительный код, сокращая объем кода, который вам нужно написать. Чтобы добавить такую ​​зависимость, необходимо добавить ее в путь к классам процессора аннотаций, используя конфигурации ksp , kapt или annotationProcessor . Использование этих конфигураций повышает производительность сборки за счет отделения пути к классам компиляции от пути к классам процессора аннотаций. Если Gradle обнаруживает обработчики аннотаций в пути к классам компиляции, он деактивирует избежание компиляции , что отрицательно влияет на время сборки (Gradle 5.0 и выше игнорируют обработчики аннотаций, найденные в пути к классам компиляции). Плагин Android Gradle предполагает, что зависимость является обработчиком аннотаций, если его JAR-файл содержит следующий файл: META-INF/services/javax.annotation.processing.Processor Если плагин обнаруживает обработчик аннотаций, находящийся в пути к классам компиляции, он выдает ошибку сборки. ksp — это процессор символов Kotlin, запускаемый компилятором Kotlin. kapt и apt — это отдельные инструменты, которые обрабатывают аннотации перед выполнением компиляторов Kotlin или Java. Принимая решение о том, какую конфигурацию использовать, учитывайте следующее: Если процессор доступен как процессор символов Kotlin, используйте его как зависимость ksp . Подробную информацию об использовании процессоров символов Kotlin см. в разделе «Миграция с kapt на ksp» . Если процессор недоступен в качестве процессора символов Kotlin: Если ваш проект включает исходный код Kotlin (но может также включать исходный код Java), используйте kapt , чтобы включить его. Если ваш проект использует только исходный код Java, используйте annotationProcessor чтобы включить его. Дополнительные сведения об использовании обработчиков аннотаций см. в разделе Добавление обработчиков аннотаций .
lintChecks	Используйте эту конфигурацию, чтобы включить библиотеку, содержащую проверки lint, которые Gradle должен выполнять при создании проекта приложения для Android. Обратите внимание, что файлы AAR, содержащие файл lint.jar будут автоматически выполнять проверки, определенные в этом файле lint.jar ; вам не нужно добавлять явную зависимость lintChecks . Это позволяет вам определять библиотеки и связанные с ними проверки ворса в одной зависимости, гарантируя, что ваши проверки будут выполняться, когда потребители используют вашу библиотеку.
lintPublish	Используйте эту конфигурацию в проектах библиотеки Android, чтобы включить проверки lint, которые Gradle должен скомпилировать в файл 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 в индексе 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'
}