הוספת תלויות 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" }

    חלק מהספריות זמינות ב-Bill of Materials (BOM) שפורסם, שמקבץ משפחות של ספריות ואת הגרסאות שלהן. אפשר לכלול BOM בקטלוג הגרסאות ובקובצי ה-build, ולאפשר לו לנהל את הגרסאות האלה בשבילכם. פרטים נוספים זמינים במאמר שימוש ברשימת הרכיבים.

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

    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.

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

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

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

מגניב

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

מגניב

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 בכל המודולים. במקום לציין את הגרסה בכל אחד מהסקריפטים של בניית המודול, צריך לכלול את התלות של הפלאגין בסקריפט של גרסת ה-root של ה-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'
}