הוספת תלויות build

מערכת ה-build של Gradle ב-Android Studio מאפשרת לכם לכלול קובצי בינארי חיצוניים או מודולים אחרים של ספריות ב-build בתור יחסי תלות. יחסי התלות יכולים להיות במכונה או במאגר מרוחק, וכל יחסי התלות הטרנזיטיביים שהם מכריזים עליהם נכללים גם כן באופן אוטומטי. בדף הזה מוסבר איך להשתמש ביחסי תלות בפרויקט Android, כולל פרטים על התנהגויות והגדרות ספציפיות לפלאגין Android Gradle (AGP). למדריך קונספטואלי מעמיק יותר בנושא יחסי תלות ב-Gradle, אפשר לעיין במדריך Gradle לניהול יחסי תלות. עם זאת, חשוב לזכור שבפרויקט Android צריך להשתמש רק בהגדרות יחסי התלות שמוגדרות בדף הזה.

הוספת תלות בספרייה או בתוסף

הדרך הטובה ביותר להוסיף ולנהל יחסי תלות ב-build היא להשתמש בקטלוגי גרסאות. זו השיטה שבה נעשה שימוש בפרויקטים חדשים כברירת מחדל. בקטע הזה נסביר על סוגי ההגדרות הנפוצים ביותר לפרויקטים של Android. אפשרויות נוספות מפורטות במסמכי העזרה של Gradle. דוגמה לאפליקציה שמשתמשת בקטלוגים של גרסאות מופיעה במאמר עכשיו ב-Android. אם כבר הגדרתם יחסי תלות ב-build בלי קטלוגים של גרסאות ויש לכם פרויקט עם כמה מודולים, מומלץ להעביר אותו.

למידע נוסף על הוספה וניהול של יחסי תלות מקומיים (לא נפוצים), ראו יחסי תלות מקומיים.

בדוגמה הבאה, אנחנו מוסיפים לפרויקט תלות בקובץ בינארי מרוחק (ספריית Jetpack Macrobenchmark), תלות במודול של ספרייה מקומית (myLibrary) ותלות בפלאגין (פלאגין Android Gradle). אלה השלבים הכלליים להוספת יחסי התלות האלה לפרויקט:

  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]
...

    כינויים יכולים לכלול מקפים או קווים תחתונים. כינויים כאלה יוצרים ערכים בתצוגת עץ שאפשר להפנות אליהם בסקריפטים ל-build. ההפניות מתחילות בשם הקטלוג, החלק 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 בקטלוג הגרסאות ובקובצי ה-build, ולאפשר לו לנהל את הגרסאות בשבילכם. לפרטים נוספים, ראו שימוש ברשימת החומרים.

  3. מוסיפים הפניה לכינוי של יחסי התלות לסקריפט ה-build של המודולים שדורשים את יחסי התלות. צריך להמיר את הקווים התחתונים והמקפים של הכינוי לנקודות כשמפנימים אליו מסקריפט build. סקריפט ה-build ברמת המודול ייראה כך:

    Kotlin

    plugins {
  alias(libs.plugins.androidApplication)
}

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

    Groovy

    plugins {
  alias 'libs.plugins.androidApplication'
}

dependencies {
  implementation libs.androidx.benchmark.macro
  implementation libs.my.library
}

    הפניות ל-Plugin כוללות את הערך plugins אחרי שם הקטלוג, והפניות לגרסה כוללות את הערך versions אחרי שם הקטלוג (הפניות לגרסה הן נדירות. דוגמאות להפניות לגרסה מפורטות בקטע יחסי תלות עם אותם מספרי גרסה). הפניות לספריות לא כוללות את המאפיין libraries, לכן אי אפשר להשתמש ב-versions או ב-plugins בתחילת כינוי לספרייה.

הגדרת יחסי תלות

בתוך הבלוק dependencies, אפשר להצהיר על תלות בספרייה באמצעות אחת מהגדרות התלות השונות (כמו implementation שצוינה למעלה). כל הגדרת תלות מספקת ל-Gradle הוראות שונות לגבי השימוש בתלות. בטבלה הבאה מתוארות כל ההגדרות שאפשר להשתמש בהן לצורך יחסי תלות בפרויקט Android.

הגדרות אישיות התנהגות
implementation Gradle מוסיף את התלות לנתיב ה-classpath של הידור ומארז את התלות בפלט של ה-build. כשהמודול מגדיר יחסי תלות מסוג implementation, הוא מאפשר ל-Gradle לדעת שאתם לא רוצים שהמודול ידלוף את יחסי התלות למודולים אחרים בזמן הידור. כלומר, התלות לא זמינה למודולים אחרים שתלויים במודול הנוכחי.

שימוש בהגדרת התלות הזו במקום ב-api יכול להוביל לשיפורים משמעותיים בזמן ה-build, כי הוא מקטין את מספר המודולים שמערכת ה-build צריכה להכין מחדש. לדוגמה, אם יחסי התלות של implementation משנים את ה-API, Gradle ידרוש קומפילציה מחדש רק של יחסי התלות האלה ושל המודולים שתלויים בהם ישירות. רוב המודולים של האפליקציות והבדיקות צריכים להשתמש בתצורה הזו.
api Gradle מוסיף את התלות לנתיב ה-classpath של הידור ולפלט של ה-build. כשמודול כולל יחסי תלות מסוג api, הוא מעדכן את Gradle שהמודול רוצה לייצא את יחסי התלות האלה באופן רציף למודולים אחרים, כדי שהם יהיו זמינים להם גם בסביבת זמן הריצה וגם בזמן הידור.

יש להשתמש בהגדרה הזו בזהירות, ורק עם יחסי תלות שצריך לייצא באופן טרנזיטי לצרכנים אחרים ב-upstream. אם יחסי התלות של api משנים את ממשק ה-API החיצוני שלהם, Gradle ידרוש קומפילציה מחדש של כל המודולים שיש להם גישה ליחסי התלות האלה בזמן הקומפילציה. אם יש מספר גדול של יחסי תלות מסוג api, זמן ה-build עשוי להתארך באופן משמעותי. אלא אם רוצים לחשוף את ה-API של יחסי התלות למודול נפרד, במודולים של הספריות צריך להשתמש במקום זאת ביחסי תלות מסוג implementation.
compileOnly Gradle מוסיף את התלות לנתיב ה-classpath של הידור בלבד (כלומר, הוא לא מתווסף לפלט ה-build). האפשרות הזו שימושית כשאתם יוצרים מודול ל-Android ואתם צריכים את התלות במהלך הידור, אבל היא לא חובה שתהיה קיימת בזמן הריצה. לדוגמה, אם אתם תלויים בספרייה שכוללת רק הערות בזמן הידור – בדרך כלל נעשה בהן שימוש ליצירת קוד, אבל לרוב הן לא נכללות בפלט ה-build – תוכלו לסמן את הספרייה הזו בתווית compileOnly.

אם משתמשים בהגדרה הזו, מודול הספרייה צריך לכלול תנאי בסביבת זמן הריצה כדי לבדוק אם התלות זמינה, ואז לשנות את ההתנהגות שלו בצורה חלקה כדי שהוא עדיין יוכל לפעול אם היא לא מסופקת. כך אפשר לצמצם את גודל האפליקציה הסופית, כי לא מוסיפים יחסי תלות זמניים שאינם קריטיים.

הערה: אי אפשר להשתמש בהגדרה compileOnly עם יחסי תלות של Android Archive ‏ (AAR).

runtimeOnly Gradle מוסיף את יחסי התלות לפלט ה-build בלבד, לשימוש במהלך זמן הריצה. כלומר, הוא לא מתווסף לנתיב ה-Classpath של הידור. השימוש ב-Log4j ב-Android נדיר, אבל הוא נפוץ באפליקציות שרת כדי לספק הטמעות של רישום ביומן. לדוגמה, אפשר להשתמש בספרייה ב-Logging API שלא כולל הטמעה. צרכני הספרייה הזו יכולים להוסיף אותה כיחס תלות implementation ולכלול יחסי תלות runtimeOnly לשימוש בהטמעת הרישום ביומן בפועל.
ksp
kapt
annotationProcessor

ההגדרות האלה מספקות ספריות שמעבדות הערות וסמלים אחרים בקוד לפני שהוא עובר הידור. בדרך כלל, הן מאמתות את הקוד או יוצרות קוד נוסף, וכך מפחיתות את כמות הקוד שצריך לכתוב.

כדי להוסיף יחסי תלות כאלה, צריך להוסיף אותם לנתיב ה-class של מעבד התווית באמצעות ההגדרות ksp,‏ kapt או annotationProcessor. השימוש בהגדרות האלה משפר את ביצועי ה-build על ידי הפרדת נתיב ה-classpath של הידור מנתיב ה-classpath של מעבד התווית. אם Gradle מוצא מעבדי הערות בנתיב ה-classpath של הידור, הוא משבית את הימנעות מהידור, שמשפיעה לרעה על זמן ה-build (ב-Gradle 5.0 ואילך, מעבדי הערות שנמצאים בנתיב ה-classpath של הידור מתעלמים).

פלאגין Android Gradle מניח שיחס תלות הוא מעבד הערות אם קובץ ה-JAR שלו מכיל את הקובץ הבא:

META-INF/services/javax.annotation.processing.Processor

אם הפלאגין מזהה מעבד הערות שנמצא במסלול ה-Classpath של הידור, הוא יוצר שגיאת build.

ksp הוא מעבד סימנים של Kotlin, והוא מופעל על ידי המהדר של Kotlin.

kapt ו-apt הם כלים נפרדים שמעבדים את ההערות לפני שהמקודדים של Kotlin או Java מפעילים אותן.

כשמחליטים באיזו תצורה להשתמש, כדאי להביא בחשבון את הדברים הבאים:

  • אם מעבד זמין כמעבד סמלים של Kotlin, אפשר להשתמש בו כיחס תלות מסוג ksp. במאמר מעבר מ-kapt ל-ksp מוסבר בהרחבה איך משתמשים במעבדי הסמלים של Kotlin.
  • אם המעבד לא זמין כמעבד סמלים של Kotlin:
    • אם הפרויקט כולל מקור Kotlin (אבל יכול גם לכלול מקור Java), משתמשים ב-kapt כדי לכלול אותו.
    • אם בפרויקט נעשה שימוש רק במקורות של Java, צריך להשתמש ב-annotationProcessor כדי לכלול אותם.

למידע נוסף על שימוש במעבדי הערות, תוכלו לקרוא את המאמר הוספת מעבדי הערות.
lintChecks

אפשר להשתמש בהגדרה הזו כדי לכלול ספרייה שמכילה בדיקות של איתור שגיאות בקוד (lint) שרוצים ש-Gradle תבצע כשמפתחים את הפרויקט של אפליקציית Android.

חשוב לזכור ש-AARs שמכילים קובץ lint.jar מריצים באופן אוטומטי את הבדיקות שמוגדרות בקובץ lint.jar הזה. אין צורך להוסיף תלות lintChecks מפורשת. כך תוכלו להגדיר ספריות ובדיקות איתור שגיאות הקשורות ביחס תלות יחיד, וכך להבטיח שהבדיקות יפעלו כשהצרכנים ישתמשו בספרייה.
lintPublish אפשר להשתמש בהגדרה הזו בפרויקטים של ספריות Android כדי לכלול בדיקות של איתור שגיאות בקוד (lint) שרוצים ש-Gradle תעבד לקובץ lint.jar ותארוז ב-AAR. כך הבדיקה תתבצע גם בפרויקטים שמשתמשים ב-AAR. אם השתמשתם בעבר בהגדרת התלות lintChecks כדי לכלול בדיקות איתור שגיאות בקוד ב-AAR שפורסם, תצטרכו להעביר את יחסי התלות האלה ולהשתמש במקום זאת בהגדרה lintPublish.

Kotlin

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"))
}

Groovy

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')
}

הגדרת יחסי תלות לגרסה ספציפית של build

כל ההגדרות הקודמות חלות על כל הגרסאות של ה-build. אם רוצים להצהיר על תלות רק בקבוצת מקורות של גרסה ספציפית של build או בקבוצת מקורות לבדיקה, צריך להשתמש באותיות רישיות בשם ההגדרה ולהוסיף לו את השם של גרסת ה-build או של קבוצת המקורות לבדיקה.

לדוגמה, כדי להוסיף יחסי תלות בינאריים מרוחקים רק למאפיין המוצר 'חינם' באמצעות ההגדרה implementation, צריך להשתמש בקוד הבא:

Kotlin

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

Groovy

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

עם זאת, אם רוצים להוסיף תלות לגרסה משולבת של טעימה של מוצר וסוג build, צריך לאתחל את שם ההגדרה:

Kotlin

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

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

Groovy

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

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

כדי להוסיף יחסי תלות של implementation לבדיקות המקומיות ולבדיקות עם מכשירי המדידה, צריך להשתמש בקוד הבא:

Kotlin

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")
}

Groovy

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 מוצגות אזהרות על שגיאות בקוד בקובץ של קטלוג הגרסאות ובתיבת הדו-שיח Project Structure לגבי ערכות SDK ציבוריות בGoogle Play SDK Index במקרים הבאים:

  • ערכות ה-SDK מסומנות כמיושנות על ידי המחברים שלהן.
  • ערכות ה-SDK מפירות את כללי המדיניות של Play.

האזהרות הן אותות לכך שעליכם לעדכן את יחסי התלות האלה, כי שימוש בגרסאות מיושנות עלול למנוע מכם לפרסם ב-Google Play Console בעתיד.

הוספת יחסי תלות ב-build ללא קטלוגים של גרסאות

מומלץ להשתמש בקטלוגים של גרסאות כדי להוסיף ולנהל יחסי תלות, אבל יכול להיות שלא תצטרכו אותם בפרויקטים פשוטים. דוגמה לקובץ build שלא משתמש בקטלוגי גרסאות:

Kotlin

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"))
}

Groovy

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')
}

קובץ ה-build הזה מצהיר על תלות בגרסה 12.3 של הספרייה app-magic, בתוך קבוצת המרחב המשותף com.example.android. ההצהרה על יחסי התלות בין קבצים בינאריים מרוחקים היא קיצור דרך לביטוי הבא:

Kotlin

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

Groovy

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

קובץ ה-build גם מכריז על תלות במודול ספרייה של Android בשם 'mylibrary'. השם הזה חייב להיות זהה לשם הספרייה שהוגדר באמצעות include: בקובץ settings.gradle.kts. כשמפתחים את האפליקציה, מערכת ה-build מקמפלת את מודול הספרייה ומארזת את התוכן המקודד שנוצר באפליקציה.

קובץ ה-build גם מצהיר על תלות ב-Android Gradle plugin‏ (com.application.android). אם יש לכם כמה מודולים שמשתמשים באותו פלאגין, תוכלו להשתמש רק בגרסה אחת של הפלאגין ב-build classpath בכל המודולים. במקום לציין את הגרסה בכל אחד מתסריטי ה-build של המודול, צריך לכלול את יחסי התלות של הפלאגין בתסריט ה-build ברמה הבסיסית עם הגרסה, ולהציין לא להחיל אותו. הוספת apply false מורה ל-Gradle לתעד את גרסת הפלאגין, אבל לא להשתמש בו ב-build ברמה הבסיסית. בדרך כלל סקריפט ה-build ברמה הבסיסית (root) ריק, מלבד הבלוק plugins הזה.

Kotlin

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

Groovy

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

אם יש לכם פרויקט עם מודול יחיד, תוכלו לציין את הגרסה באופן מפורש בסקריפט ה-build ברמת המודול ולהשאיר את סקריפט ה-build ברמת הפרויקט ריק:

Kotlin

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

Groovy

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